feat(search): return human-readable label with every SearchResult

Add `label` field to SearchResult so search responses are self-contained
and the UI can render results without a follow-up fetch for each id.

- types: SearchResult.label, SearchConfig.labelColumn
- lib/search: hybridSearch SQL selects p.<labelColumn> in both FTS and
  vec branches; carries label through RRF fusion (FTS label takes
  priority on collision)
- stores: each passes its labelColumn — knowledge/docs='title',
  code='name', tasks='title', skills='title', epics='title'
- files: separate non-shared search path uses file_path as label
- tests: SearchConfig fixture updated; existing search assertions hold
- ui/entities: search APIs typed as { id, label, score } instead of
  Entity & { score } — drops dependency on full entity shape
- ui/pages: search/code/docs/files/knowledge/skills render label
  directly; removes per-result entity fetch

Author: prih

src/store/sqlite/lib/search.ts

@@ -41,6 +41,8 @@ export interface SearchConfig {
   parentTable: string;
   /** Column to join parent table to FTS rowid (usually 'id') */
   parentIdColumn: string;
+  /** Column on parent table to expose as a human-readable label (title / name) */
+  labelColumn: string;
   /** Optional extra SQL appended to the JOIN condition on parent table (e.g. "AND p.kind = 'file'") */
   extraJoinCondition?: string;
 }
@@ -65,14 +67,15 @@ export function hybridSearch(
   const maxResults = query.maxResults ?? 20;
   const minScore = query.minScore ?? 0;
 
-  let ftsRanked: Array<{ id: number; rn: number }> = [];
-  let vecRanked: Array<{ id: number; rn: number }> = [];
+  let ftsRanked: Array<{ id: number; rn: number; label: string }> = [];
+  let vecRanked: Array<{ id: number; rn: number; label: string }> = [];
 
   // Validate config identifiers to prevent SQL injection
   assertIdentifier(config.ftsTable, 'ftsTable');
   assertIdentifier(config.vecTable, 'vecTable');
   assertIdentifier(config.parentTable, 'parentTable');
   assertIdentifier(config.parentIdColumn, 'parentIdColumn');
+  assertIdentifier(config.labelColumn, 'labelColumn');
 
   const extraJoin = config.extraJoinCondition ?? '';
 
@@ -82,14 +85,14 @@ export function hybridSearch(
     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
+        SELECT p.${config.parentIdColumn} AS id, p.${config.labelColumn} AS label, 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 }>;
+      `).all(projectId, escaped, topK) as Array<{ id: bigint; label: string | null; rn: bigint }>;
 
-      ftsRanked = rows.map(r => ({ id: num(r.id), rn: num(r.rn) }));
+      ftsRanked = rows.map(r => ({ id: num(r.id), rn: num(r.rn), label: r.label ?? '' }));
     }
   }
 
@@ -100,41 +103,44 @@ export function hybridSearch(
     const vecK = topK * 3;
 
     const rows = db.prepare(`
-      SELECT v.rowid AS id, v.distance
+      SELECT v.rowid AS id, p.${config.labelColumn} AS label, 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 }>;
+    `).all(projectId, embeddingBuf, vecK) as Array<{ id: bigint; label: string | null; distance: number }>;
 
-    vecRanked = rows.slice(0, topK).map((r, i) => ({ id: num(r.id), rn: i + 1 }));
+    vecRanked = rows.slice(0, topK).map((r, i) => ({ id: num(r.id), rn: i + 1, label: r.label ?? '' }));
   }
 
   // Single-mode: return directly with normalized scores
   if (mode === 'keyword') {
     return ftsRanked
-      .map(r => ({ id: r.id, score: 1 / (RRF_K + r.rn) }))
+      .map(r => ({ id: r.id, score: 1 / (RRF_K + r.rn), label: r.label }))
       .filter(r => r.score >= minScore)
       .slice(0, maxResults);
   }
 
   if (mode === 'vector') {
     return vecRanked
-      .map(r => ({ id: r.id, score: 1 / (RRF_K + r.rn) }))
+      .map(r => ({ id: r.id, score: 1 / (RRF_K + r.rn), label: r.label }))
       .filter(r => r.score >= minScore)
       .slice(0, maxResults);
   }
 
   // Hybrid: RRF fusion
   const scores = new Map<number, number>();
+  const labels = new Map<number, string>();
   for (const r of ftsRanked) {
     scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (RRF_K + r.rn));
+    labels.set(r.id, r.label);
   }
   for (const r of vecRanked) {
     scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (RRF_K + r.rn));
+    if (!labels.has(r.id)) labels.set(r.id, r.label);
   }
 
   return [...scores.entries()]
-    .map(([id, score]) => ({ id, score }))
+    .map(([id, score]) => ({ id, score, label: labels.get(id) ?? '' }))
     .filter(r => r.score >= minScore)
     .sort((a, b) => b.score - a.score)
     .slice(0, maxResults);

src/store/sqlite/stores/code.ts

@@ -15,7 +15,7 @@ import * as path from 'path';
 const GRAPH = 'code';
 
 const SEARCH_CONFIG: SearchConfig = {
-  ftsTable: 'code_fts', vecTable: 'code_vec', parentTable: 'code', parentIdColumn: 'id',
+  ftsTable: 'code_fts', vecTable: 'code_vec', parentTable: 'code', parentIdColumn: 'id', labelColumn: 'name',
 };
 
 export class SqliteCodeStore implements CodeStore {

src/store/sqlite/stores/docs.ts

@@ -14,7 +14,7 @@ import { hybridSearch, SearchConfig } from '../lib/search';
 const GRAPH = 'docs';
 
 const SEARCH_CONFIG: SearchConfig = {
-  ftsTable: 'docs_fts', vecTable: 'docs_vec', parentTable: 'docs', parentIdColumn: 'id',
+  ftsTable: 'docs_fts', vecTable: 'docs_vec', parentTable: 'docs', parentIdColumn: 'id', labelColumn: 'title',
 };
 
 export class SqliteDocsStore implements DocsStore {

src/store/sqlite/stores/epics.ts

@@ -23,7 +23,7 @@ const GRAPH = 'epics';
 const ORDER_GAP = 1000;
 
 const SEARCH_CONFIG: SearchConfig = {
-  ftsTable: 'epics_fts', vecTable: 'epics_vec', parentTable: 'epics', parentIdColumn: 'id',
+  ftsTable: 'epics_fts', vecTable: 'epics_vec', parentTable: 'epics', parentIdColumn: 'id', labelColumn: 'title',
 };
 
 export class SqliteEpicsStore implements EpicsStore {

src/store/sqlite/stores/files.ts

@@ -219,12 +219,12 @@ export class SqliteFilesStore implements FilesStore {
     if (mode === 'keyword' && query.text) {
       // Fallback: LIKE-based search on file_path
       const rows = this.db.prepare(`
-        SELECT id FROM files WHERE project_id = ? AND file_path LIKE ? ESCAPE '\\' AND kind = 'file'
+        SELECT id, file_path FROM files WHERE project_id = ? AND file_path LIKE ? ESCAPE '\\' AND kind = 'file'
         ORDER BY file_path ASC LIMIT ?
-      `).all(this.projectId, `%${likeEscape(query.text)}%`, maxResults) as Array<{ id: bigint }>;
+      `).all(this.projectId, `%${likeEscape(query.text)}%`, maxResults) as Array<{ id: bigint; file_path: string }>;
 
       return rows
-        .map((r, i) => ({ id: num(r.id), score: 1 / (60 + i + 1) }))
+        .map((r, i) => ({ id: num(r.id), score: 1 / (60 + i + 1), label: r.file_path }))
         .filter(r => r.score >= minScore);
     }
 
@@ -234,50 +234,57 @@ export class SqliteFilesStore implements FilesStore {
       const topK = query.topK ?? 50;
 
       const rows = this.db.prepare(`
-        SELECT v.rowid AS id, v.distance
+        SELECT v.rowid AS id, p.file_path, v.distance
         FROM files_vec v
         JOIN files p ON p.id = v.rowid AND p.project_id = ? AND p.kind = 'file'
         WHERE v.embedding MATCH ? AND v.k = ?
-      `).all(this.projectId, embeddingBuf, topK * 3) as Array<{ id: bigint; distance: number }>;
+      `).all(this.projectId, embeddingBuf, topK * 3) as Array<{ id: bigint; file_path: string; distance: number }>;
 
       return rows.slice(0, maxResults)
-        .map((r, i) => ({ id: num(r.id), score: 1 / (60 + i + 1) }))
+        .map((r, i) => ({ id: num(r.id), score: 1 / (60 + i + 1), label: r.file_path }))
         .filter(r => r.score >= minScore);
     }
 
     // Hybrid: combine LIKE + vector
     if (mode === 'hybrid') {
-      const likeResults: Array<{ id: number; rn: number }> = [];
-      const vecResults: Array<{ id: number; rn: number }> = [];
+      const likeResults: Array<{ id: number; rn: number; label: string }> = [];
+      const vecResults: Array<{ id: number; rn: number; label: string }> = [];
 
       if (query.text) {
         const rows = this.db.prepare(`
-          SELECT id FROM files WHERE project_id = ? AND file_path LIKE ? ESCAPE '\\' AND kind = 'file'
+          SELECT id, file_path FROM files WHERE project_id = ? AND file_path LIKE ? ESCAPE '\\' AND kind = 'file'
           ORDER BY file_path ASC LIMIT ?
-        `).all(this.projectId, `%${likeEscape(query.text)}%`, query.topK ?? 50) as Array<{ id: bigint }>;
-        rows.forEach((r, i) => likeResults.push({ id: num(r.id), rn: i + 1 }));
+        `).all(this.projectId, `%${likeEscape(query.text)}%`, query.topK ?? 50) as Array<{ id: bigint; file_path: string }>;
+        rows.forEach((r, i) => likeResults.push({ id: num(r.id), rn: i + 1, label: r.file_path }));
       }
 
       if (query.embedding) {
         const embeddingBuf = Buffer.from(new Float32Array(query.embedding).buffer);
         const topK = query.topK ?? 50;
         const rows = this.db.prepare(`
-          SELECT v.rowid AS id, v.distance
+          SELECT v.rowid AS id, p.file_path, v.distance
           FROM files_vec v
           JOIN files p ON p.id = v.rowid AND p.project_id = ? AND p.kind = 'file'
           WHERE v.embedding MATCH ? AND v.k = ?
-        `).all(this.projectId, embeddingBuf, topK * 3) as Array<{ id: bigint; distance: number }>;
-        rows.slice(0, topK).forEach((r, i) => vecResults.push({ id: num(r.id), rn: i + 1 }));
+        `).all(this.projectId, embeddingBuf, topK * 3) as Array<{ id: bigint; file_path: string; distance: number }>;
+        rows.slice(0, topK).forEach((r, i) => vecResults.push({ id: num(r.id), rn: i + 1, label: r.file_path }));
       }
 
       // RRF fusion
       const K = 60;
       const scores = new Map<number, number>();
-      for (const r of likeResults) scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (K + r.rn));
-      for (const r of vecResults) scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (K + r.rn));
+      const labels = new Map<number, string>();
+      for (const r of likeResults) {
+        scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (K + r.rn));
+        labels.set(r.id, r.label);
+      }
+      for (const r of vecResults) {
+        scores.set(r.id, (scores.get(r.id) ?? 0) + 1 / (K + r.rn));
+        if (!labels.has(r.id)) labels.set(r.id, r.label);
+      }
 
       return [...scores.entries()]
-        .map(([id, score]) => ({ id, score }))
+        .map(([id, score]) => ({ id, score, label: labels.get(id) ?? '' }))
         .filter(r => r.score >= minScore)
         .sort((a, b) => b.score - a.score)
         .slice(0, maxResults);

src/store/sqlite/stores/knowledge.ts

@@ -24,6 +24,7 @@ const SEARCH_CONFIG: SearchConfig = {
   vecTable: 'knowledge_vec',
   parentTable: 'knowledge',
   parentIdColumn: 'id',
+  labelColumn: 'title',
 };
 
 export class SqliteKnowledgeStore implements KnowledgeStore {

src/store/sqlite/stores/skills.ts

@@ -20,7 +20,7 @@ import { hybridSearch, SearchConfig } from '../lib/search';
 const GRAPH = 'skills';
 
 const SEARCH_CONFIG: SearchConfig = {
-  ftsTable: 'skills_fts', vecTable: 'skills_vec', parentTable: 'skills', parentIdColumn: 'id',
+  ftsTable: 'skills_fts', vecTable: 'skills_vec', parentTable: 'skills', parentIdColumn: 'id', labelColumn: 'title',
 };
 
 export class SqliteSkillsStore implements SkillsStore {

src/store/sqlite/stores/tasks.ts

@@ -23,7 +23,7 @@ const GRAPH_TASKS = 'tasks';
 const ORDER_GAP = 1000;
 
 const TASK_SEARCH_CONFIG: SearchConfig = {
-  ftsTable: 'tasks_fts', vecTable: 'tasks_vec', parentTable: 'tasks', parentIdColumn: 'id',
+  ftsTable: 'tasks_fts', vecTable: 'tasks_vec', parentTable: 'tasks', parentIdColumn: 'id', labelColumn: 'title',
 };
 
 const TERMINAL_STATUSES = new Set<string>(['done', 'cancelled']);

src/store/types/common.ts

@@ -26,6 +26,8 @@ export interface SearchQuery {
 export interface SearchResult {
   id: number;
   score: number;
+  /** Human-readable label (title / name / file_path) returned by the search query */
+  label: string;
 }
 
 // ---------------------------------------------------------------------------

src/tests/store/sqlite/search-edge-cases.test.ts

@@ -28,6 +28,7 @@ describe('hybridSearch edge cases', () => {
     vecTable: 'test_vec',
     parentTable: 'test_items',
     parentIdColumn: 'id',
+    labelColumn: 'title',
   };
   const projectId = 1;