fix(store): comprehensive audit fixes — search, validation, types, perf

- Fix hybrid search early return: operator-only text in hybrid mode now
  falls back to vector search instead of returning empty
- Fix bumpUsage not incrementing version (broke optimistic locking)
- Fix likeEscape not escaping backslash (LIKE ESCAPE '\' vulnerability)
- Fix double now() calls producing inconsistent timestamps in bulkMove,
  bulkPriority, bumpUsage
- Add IN-clause chunking (SQL_CHUNK_SIZE=900) to prevent hitting
  SQLite SQLITE_MAX_VARIABLE_NUMBER limit in batch operations
- Add LIMIT 10000 to listEdges to prevent unbounded queries
- Add migration v002: composite index on attachments(project_id, graph, entity_id)
- Add evictProject() to Store for cache invalidation after project deletion
- Refactor KnowledgeStore.list() from positional args to NoteListOptions object
- Wire FileNode.language/mimeType through updateFile via FileUpdateOptions
- Add order field to EpicCreate/EpicPatch + reorder() method
- Remove dead TagRecord type
- Add assertEmbeddingDim() validation on all embedding inserts
- Optimize setTags: reuse prepared statements instead of re-preparing per tag
- Remove unused ROW_NUMBER() from vec0 search query

Author: prih

src/store/sqlite/lib/bigint.ts

@@ -8,9 +8,34 @@ export function now(): bigint {
   return BigInt(Date.now());
 }
 
-/** Escape LIKE special characters (%, _) for safe use in SQL LIKE patterns */
+/** Escape LIKE special characters (\, %, _) for safe use in SQL LIKE patterns with ESCAPE '\' */
 export function likeEscape(text: string): string {
-  return text.replace(/[%_]/g, '\\$&');
+  return text.replace(/\\/g, '\\\\').replace(/[%_]/g, '\\$&');
+}
+
+import { EMBEDDING_DIM } from '../migrations/v001';
+
+/** Assert that an embedding has the expected dimensionality */
+export function assertEmbeddingDim(embedding: number[]): void {
+  if (embedding.length !== EMBEDDING_DIM) {
+    throw new Error(`Embedding dimension mismatch: expected ${EMBEDDING_DIM}, got ${embedding.length}`);
+  }
+}
+
+/**
+ * Max items per SQL IN-clause to stay within SQLite's SQLITE_MAX_VARIABLE_NUMBER.
+ * Reserves a few slots for other query params.
+ */
+export const SQL_CHUNK_SIZE = 900;
+
+/** Split an array into chunks of at most `size` elements */
+export function chunk<T>(arr: T[], size: number = SQL_CHUNK_SIZE): T[][] {
+  if (arr.length <= size) return [arr];
+  const result: T[][] = [];
+  for (let i = 0; i < arr.length; i += size) {
+    result.push(arr.slice(i, i + size));
+  }
+  return result;
 }
 
 /** Safely parse JSON with a fallback for corrupted data */

src/store/sqlite/lib/edge-helper.ts

@@ -36,7 +36,7 @@ export class EdgeHelper {
 
     const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
     const rows = this.db.prepare(
-      `SELECT from_graph, from_id, to_graph, to_id, kind FROM edges ${where}`
+      `SELECT from_graph, from_id, to_graph, to_id, kind FROM edges ${where} LIMIT 10000`
     ).all(...params) as Array<Record<string, unknown>>;
 
     return rows.map(r => ({

src/store/sqlite/lib/entity-helpers.ts

@@ -1,6 +1,6 @@
 import Database from 'better-sqlite3';
 import type { AttachmentMeta, Edge, GraphName } from '../../types';
-import { num } from './bigint';
+import { num, chunk } from './bigint';
 
 /**
  * Shared helpers for user-managed stores (knowledge, tasks, skills).
@@ -32,13 +32,15 @@ export class EntityHelpers {
       `).run(this.projectId, ...ids);
     }
 
-    // Insert new tags
+    // Insert new tags — use INSERT OR IGNORE + SELECT per tag
+    const insertTag = this.db.prepare('INSERT OR IGNORE INTO tags (project_id, name) VALUES (?, ?)');
+    const selectTag = this.db.prepare('SELECT id FROM tags WHERE project_id = ? AND name = ?');
+    const insertEdge = this.db.prepare(`INSERT INTO edges (project_id, from_graph, from_id, to_graph, to_id, kind) VALUES (?, 'tags', ?, ?, ?, 'tagged')`);
     for (const tag of tags) {
-      this.db.prepare('INSERT OR IGNORE INTO tags (project_id, name) VALUES (?, ?)').run(this.projectId, tag);
-      const row = this.db.prepare('SELECT id FROM tags WHERE project_id = ? AND name = ?').get(this.projectId, tag) as { id: bigint } | undefined;
+      insertTag.run(this.projectId, tag);
+      const row = selectTag.get(this.projectId, tag) as { id: bigint } | undefined;
       if (!row) throw new Error(`Failed to resolve tag: ${tag}`);
-      this.db.prepare(`INSERT INTO edges (project_id, from_graph, from_id, to_graph, to_id, kind) VALUES (?, 'tags', ?, ?, ?, 'tagged')`)
-        .run(this.projectId, num(row.id), graph, entityId);
+      insertEdge.run(this.projectId, num(row.id), graph, entityId);
     }
   }
 
@@ -58,20 +60,22 @@ export class EntityHelpers {
     if (entityIds.length === 0) return result;
     for (const id of entityIds) result.set(id, []);
 
-    const ph = entityIds.map(() => '?').join(',');
-    const rows = this.db.prepare(`
-      SELECT e.to_id AS entity_id, t.name
-      FROM edges e
-      JOIN tags t ON t.id = e.from_id AND t.project_id = e.project_id
-      WHERE e.project_id = ? AND e.from_graph = 'tags' AND e.to_graph = ? AND e.kind = 'tagged'
-      AND e.to_id IN (${ph})
-      ORDER BY t.name
-    `).all(this.projectId, graph, ...entityIds) as Array<{ entity_id: bigint; name: string }>;
-
-    for (const r of rows) {
-      const id = num(r.entity_id);
-      const arr = result.get(id);
-      if (arr) arr.push(r.name);
+    for (const batch of chunk(entityIds)) {
+      const ph = batch.map(() => '?').join(',');
+      const rows = this.db.prepare(`
+        SELECT e.to_id AS entity_id, t.name
+        FROM edges e
+        JOIN tags t ON t.id = e.from_id AND t.project_id = e.project_id
+        WHERE e.project_id = ? AND e.from_graph = 'tags' AND e.to_graph = ? AND e.kind = 'tagged'
+        AND e.to_id IN (${ph})
+        ORDER BY t.name
+      `).all(this.projectId, graph, ...batch) as Array<{ entity_id: bigint; name: string }>;
+
+      for (const r of rows) {
+        const id = num(r.entity_id);
+        const arr = result.get(id);
+        if (arr) arr.push(r.name);
+      }
     }
     return result;
   }
@@ -92,17 +96,19 @@ export class EntityHelpers {
     if (entityIds.length === 0) return result;
     for (const id of entityIds) result.set(id, []);
 
-    const ph = entityIds.map(() => '?').join(',');
-    const rows = this.db.prepare(`
-      SELECT entity_id, filename, mime_type, size, url, added_at FROM attachments
-      WHERE project_id = ? AND graph = ? AND entity_id IN (${ph})
-      ORDER BY added_at
-    `).all(this.projectId, graph, ...entityIds) as Array<Record<string, unknown>>;
-
-    for (const r of rows) {
-      const id = num(r.entity_id as bigint);
-      const arr = result.get(id);
-      if (arr) arr.push(this.toAttachmentMeta(r));
+    for (const batch of chunk(entityIds)) {
+      const ph = batch.map(() => '?').join(',');
+      const rows = this.db.prepare(`
+        SELECT entity_id, filename, mime_type, size, url, added_at FROM attachments
+        WHERE project_id = ? AND graph = ? AND entity_id IN (${ph})
+        ORDER BY added_at
+      `).all(this.projectId, graph, ...batch) as Array<Record<string, unknown>>;
+
+      for (const r of rows) {
+        const id = num(r.entity_id as bigint);
+        const arr = result.get(id);
+        if (arr) arr.push(this.toAttachmentMeta(r));
+      }
     }
     return result;
   }

src/store/sqlite/lib/search.ts

@@ -80,16 +80,18 @@ export function hybridSearch(
   // FTS5 keyword search
   if (mode !== 'vector' && query.text) {
     const escaped = ftsEscape(query.text);
-    if (!escaped) return [];
-    const rows = db.prepare(`
-      SELECT p.${config.parentIdColumn} AS id, ROW_NUMBER() OVER (ORDER BY rank) AS rn
-      FROM ${config.ftsTable} fts
-      JOIN ${config.parentTable} p ON p.${config.parentIdColumn} = fts.rowid AND p.project_id = ? ${extraJoin}
-      WHERE ${config.ftsTable} MATCH ?
-      LIMIT ?
-    `).all(projectId, escaped, topK) as Array<{ id: bigint; rn: bigint }>;
-
-    ftsRanked = rows.map(r => ({ id: num(r.id), rn: num(r.rn) }));
+    if (!escaped && mode === 'keyword') return [];
+    if (escaped) {
+      const rows = db.prepare(`
+        SELECT p.${config.parentIdColumn} AS id, ROW_NUMBER() OVER (ORDER BY rank) AS rn
+        FROM ${config.ftsTable} fts
+        JOIN ${config.parentTable} p ON p.${config.parentIdColumn} = fts.rowid AND p.project_id = ? ${extraJoin}
+        WHERE ${config.ftsTable} MATCH ?
+        LIMIT ?
+      `).all(projectId, escaped, topK) as Array<{ id: bigint; rn: bigint }>;
+
+      ftsRanked = rows.map(r => ({ id: num(r.id), rn: num(r.rn) }));
+    }
   }
 
   // vec0 vector search
@@ -99,11 +101,11 @@ export function hybridSearch(
     const vecK = topK * 3;
 
     const rows = db.prepare(`
-      SELECT v.rowid AS id, v.distance, ROW_NUMBER() OVER (ORDER BY v.distance) AS rn
+      SELECT v.rowid AS id, v.distance
       FROM ${config.vecTable} v
       JOIN ${config.parentTable} p ON p.${config.parentIdColumn} = v.rowid AND p.project_id = ? ${extraJoin}
       WHERE v.embedding MATCH ? AND v.k = ?
-    `).all(projectId, embeddingBuf, vecK) as Array<{ id: bigint; distance: number; rn: bigint }>;
+    `).all(projectId, embeddingBuf, vecK) as Array<{ id: bigint; distance: number }>;
 
     vecRanked = rows.slice(0, topK).map((r, i) => ({ id: num(r.id), rn: i + 1 }));
   }

src/store/sqlite/migrations/v001.ts

@@ -1,6 +1,6 @@
 import type { Migration } from '../lib/migrate';
 
-const EMBEDDING_DIM = 384;
+export const EMBEDDING_DIM = 384;
 
 export const v001: Migration = {
   version: 1,

src/store/sqlite/migrations/v002.ts

@@ -0,0 +1,9 @@
+import type { Migration } from '../lib/migrate';
+
+export const v002: Migration = {
+  version: 2,
+  sql: `
+-- Composite index for attachment lookups (project_id, graph, entity_id)
+CREATE INDEX IF NOT EXISTS idx_attachments_entity ON attachments(project_id, graph, entity_id);
+`,
+};

src/store/sqlite/store.ts

@@ -14,11 +14,12 @@ import { runMigrations } from './lib/migrate';
 import { MetaHelper } from './lib/meta';
 import { EdgeHelper } from './lib/edge-helper';
 import { v001 } from './migrations/v001';
+import { v002 } from './migrations/v002';
 import { SqliteTeamStore } from './stores/team';
 import { SqliteProjectsStore } from './stores/projects';
 import { SqliteProjectScopedStore } from './stores/project-scoped';
 
-const ALL_MIGRATIONS = [v001];
+const ALL_MIGRATIONS = [v001, v002];
 
 export class SqliteStore implements Store {
   private db: Database.Database | null = null;
@@ -76,6 +77,11 @@ export class SqliteStore implements Store {
     return scoped;
   }
 
+  /** Evict a project from the scoped store cache (call after project deletion) */
+  evictProject(projectId: number): void {
+    this.scopedCache.delete(projectId);
+  }
+
   // --- Edges ---
 
   createEdge(projectId: number, edge: Edge): void {

src/store/sqlite/stores/epics.ts

@@ -16,7 +16,7 @@ import type {
 import { VersionConflictError } from '../../types';
 import { MetaHelper } from '../lib/meta';
 import { EntityHelpers } from '../lib/entity-helpers';
-import { num, now, likeEscape } from '../lib/bigint';
+import { num, now, likeEscape, chunk, assertEmbeddingDim } from '../lib/bigint';
 import { hybridSearch, SearchConfig } from '../lib/search';
 
 const GRAPH = 'epics';
@@ -81,20 +81,22 @@ export class SqliteEpicsStore implements EpicsStore {
     if (epicIds.length === 0) return result;
     for (const id of epicIds) result.set(id, { total: 0, done: 0 });
 
-    const ph = epicIds.map(() => '?').join(',');
-    const rows = this.db.prepare(`
-      SELECT e.from_id AS epic_id,
-        COALESCE(SUM(CASE WHEN t.status != 'cancelled' THEN 1 ELSE 0 END), 0) AS total,
-        COALESCE(SUM(CASE WHEN t.status = 'done' THEN 1 ELSE 0 END), 0) AS done
-      FROM edges e
-      JOIN tasks t ON t.id = e.to_id AND t.project_id = e.project_id
-      WHERE e.project_id = ? AND e.from_graph = 'epics' AND e.to_graph = 'tasks' AND e.kind = 'belongs_to'
-      AND e.from_id IN (${ph})
-      GROUP BY e.from_id
-    `).all(this.projectId, ...epicIds) as Array<{ epic_id: bigint; total: bigint; done: bigint }>;
-
-    for (const r of rows) {
-      result.set(num(r.epic_id), { total: num(r.total), done: num(r.done) });
+    for (const batch of chunk(epicIds)) {
+      const ph = batch.map(() => '?').join(',');
+      const rows = this.db.prepare(`
+        SELECT e.from_id AS epic_id,
+          COALESCE(SUM(CASE WHEN t.status != 'cancelled' THEN 1 ELSE 0 END), 0) AS total,
+          COALESCE(SUM(CASE WHEN t.status = 'done' THEN 1 ELSE 0 END), 0) AS done
+        FROM edges e
+        JOIN tasks t ON t.id = e.to_id AND t.project_id = e.project_id
+        WHERE e.project_id = ? AND e.from_graph = 'epics' AND e.to_graph = 'tasks' AND e.kind = 'belongs_to'
+        AND e.from_id IN (${ph})
+        GROUP BY e.from_id
+      `).all(this.projectId, ...batch) as Array<{ epic_id: bigint; total: bigint; done: bigint }>;
+
+      for (const r of rows) {
+        result.set(num(r.epic_id), { total: num(r.total), done: num(r.done) });
+      }
     }
     return result;
   }
@@ -104,14 +106,16 @@ export class SqliteEpicsStore implements EpicsStore {
   // =========================================================================
 
   create(data: EpicCreate, embedding: number[]): EpicRecord {
+    assertEmbeddingDim(embedding);
     const slug = randomUUID();
     const ts = now();
     const authorId = data.authorId ?? null;
 
+    const order = data.order ?? this.nextOrder();
     const result = this.db.prepare(`
       INSERT INTO epics (project_id, slug, title, description, status, priority, "order", version, created_by_id, updated_by_id, created_at, updated_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?)
-    `).run(this.projectId, slug, data.title, data.description ?? '', data.status ?? 'open', data.priority ?? 'medium', this.nextOrder(), authorId, authorId, ts, ts);
+    `).run(this.projectId, slug, data.title, data.description ?? '', data.status ?? 'open', data.priority ?? 'medium', order, authorId, authorId, ts, ts);
     const id = result.lastInsertRowid;
 
     this.db.prepare('INSERT INTO epics_vec (rowid, embedding) VALUES (?, ?)').run(BigInt(id as number | bigint), Buffer.from(new Float32Array(embedding).buffer));
@@ -138,6 +142,7 @@ export class SqliteEpicsStore implements EpicsStore {
     if (patch.description !== undefined) set('description', patch.description);
     if (patch.status !== undefined) set('status', patch.status);
     if (patch.priority !== undefined) set('priority', patch.priority);
+    if (patch.order !== undefined) set('"order"', patch.order);
 
     set('version', num(row.version as bigint) + 1);
     set('updated_by_id', authorId ?? null);
@@ -147,6 +152,7 @@ export class SqliteEpicsStore implements EpicsStore {
     this.db.prepare(`UPDATE epics SET ${fields.join(', ')} WHERE id = ? AND project_id = ?`).run(...params);
 
     if (embedding) {
+      assertEmbeddingDim(embedding);
       this.db.prepare('DELETE FROM epics_vec WHERE rowid = ?').run(BigInt(epicId));
       this.db.prepare('INSERT INTO epics_vec (rowid, embedding) VALUES (?, ?)').run(BigInt(epicId), Buffer.from(new Float32Array(embedding).buffer));
     }
@@ -215,6 +221,10 @@ export class SqliteEpicsStore implements EpicsStore {
     return row.m ? num(row.m) + ORDER_GAP : ORDER_GAP;
   }
 
+  reorder(epicId: number, order: number, authorId?: number): EpicRecord {
+    return this.update(epicId, { order }, null, authorId);
+  }
+
   // =========================================================================
   // Link / Unlink tasks
   // =========================================================================

src/store/sqlite/stores/files.ts

@@ -4,11 +4,12 @@ import type {
   FilesStore,
   FileNode,
   FileListOptions,
+  FileUpdateOptions,
   SearchQuery,
   SearchResult,
 } from '../../types';
 import { MetaHelper } from '../lib/meta';
-import { num, likeEscape } from '../lib/bigint';
+import { num, likeEscape, assertEmbeddingDim } from '../lib/bigint';
 
 const GRAPH = 'files';
 
@@ -68,11 +69,14 @@ export class SqliteFilesStore implements FilesStore {
   // updateFile
   // =========================================================================
 
-  updateFile(filePath: string, size: number, mtime: number, embedding: number[]): void {
+  updateFile(filePath: string, size: number, mtime: number, embedding: number[], opts?: FileUpdateOptions): void {
+    assertEmbeddingDim(embedding);
     const run = this.db.transaction(() => {
       const fileName = path.basename(filePath);
       const directory = path.dirname(filePath);
       const extension = path.extname(filePath);
+      const language = opts?.language ?? null;
+      const mimeType = opts?.mimeType ?? null;
 
       // Ensure parent directory exists
       if (directory && directory !== '.') {
@@ -90,9 +94,9 @@ export class SqliteFilesStore implements FilesStore {
         fileId = num(existing.id);
         // Update existing
         this.db.prepare(`
-          UPDATE files SET file_name = ?, directory = ?, extension = ?, size = ?, mtime = ?
+          UPDATE files SET file_name = ?, directory = ?, extension = ?, language = ?, mime_type = ?, size = ?, mtime = ?
           WHERE id = ? AND project_id = ?
-        `).run(fileName, directory, extension, size, mtime, fileId, this.projectId);
+        `).run(fileName, directory, extension, language, mimeType, size, mtime, fileId, this.projectId);
 
         // Update vec0 (DELETE + INSERT pattern)
         this.db.prepare('DELETE FROM files_vec WHERE rowid = ?').run(BigInt(fileId));
@@ -101,9 +105,9 @@ export class SqliteFilesStore implements FilesStore {
       } else {
         // Insert new file
         const result = this.db.prepare(`
-          INSERT INTO files (project_id, kind, file_path, file_name, directory, extension, size, mtime)
-          VALUES (?, 'file', ?, ?, ?, ?, ?, ?)
-        `).run(this.projectId, filePath, fileName, directory, extension, size, mtime);
+          INSERT INTO files (project_id, kind, file_path, file_name, directory, extension, language, mime_type, size, mtime)
+          VALUES (?, 'file', ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(this.projectId, filePath, fileName, directory, extension, language, mimeType, size, mtime);
         fileId = num(result.lastInsertRowid as bigint);
 
         // Insert vec0