contextgit 0.0.1 → 0.0.2

package/packages/store/src/local/queries.ts

@@ -0,0 +1,760 @@
+// All SQL queries for LocalStore.
+// Dates are stored as INTEGER (Unix ms) and converted to/from Date at this layer.
+// IDs are generated by the caller (nanoid).
+
+import type { Database, Statement } from 'better-sqlite3'
+import type {
+  Agent,
+  AgentInput,
+  Branch,
+  BranchInput,
+  Claim,
+  ClaimInput,
+  Commit,
+  CommitInput,
+  Pagination,
+  Project,
+  ProjectInput,
+  SearchResult,
+  SessionSnapshot,
+  Thread,
+} from '@contextgit/core'
+
+// ─── Row types (SQLite column names → snake_case) ───────────────────────────
+
+interface ProjectRow {
+  id: string
+  name: string
+  description: string | null
+  github_url: string | null
+  created_at: number
+}
+
+interface BranchRow {
+  id: string
+  project_id: string
+  name: string
+  git_branch: string
+  github_pr_url: string | null
+  parent_branch_id: string | null
+  head_commit_id: string | null
+  status: string
+  created_at: number
+  merged_at: number | null
+}
+
+interface CommitRow {
+  id: string
+  branch_id: string
+  parent_id: string | null
+  merge_source_branch_id: string | null
+  agent_id: string
+  agent_role: string
+  tool: string
+  workflow_type: string
+  loop_iteration: number | null
+  ci_run_id: string | null
+  pipeline_name: string | null
+  message: string
+  content: string
+  summary: string
+  commit_type: string
+  git_commit_sha: string | null
+  created_at: number
+}
+
+interface ThreadRow {
+  id: string
+  project_id: string
+  branch_id: string
+  description: string
+  status: string
+  workflow_type: string | null
+  opened_in_commit: string
+  closed_in_commit: string | null
+  closed_note: string | null
+  created_at: number
+}
+
+interface AgentRow {
+  id: string
+  project_id: string
+  role: string
+  tool: string
+  workflow_type: string
+  display_name: string | null
+  total_commits: number
+  last_seen: number
+  created_at: number
+}
+
+interface ClaimRow {
+  id: string
+  project_id: string
+  branch_id: string
+  task: string
+  agent_id: string
+  role: string
+  claimed_at: number
+  status: string
+  ttl: number
+  released_at: number | null
+}
+
+// ─── Row → domain type converters ───────────────────────────────────────────
+
+function toProject(row: ProjectRow): Project {
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description ?? undefined,
+    githubUrl: row.github_url ?? undefined,
+    createdAt: new Date(row.created_at),
+  }
+}
+
+function toBranch(row: BranchRow): Branch {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    name: row.name,
+    gitBranch: row.git_branch,
+    githubPrUrl: row.github_pr_url ?? undefined,
+    parentBranchId: row.parent_branch_id ?? undefined,
+    headCommitId: row.head_commit_id ?? undefined,
+    status: row.status as Branch['status'],
+    createdAt: new Date(row.created_at),
+    mergedAt: row.merged_at ? new Date(row.merged_at) : undefined,
+  }
+}
+
+function toCommit(row: CommitRow): Commit {
+  return {
+    id: row.id,
+    branchId: row.branch_id,
+    parentId: row.parent_id ?? undefined,
+    mergeSourceBranchId: row.merge_source_branch_id ?? undefined,
+    agentId: row.agent_id,
+    agentRole: row.agent_role as Commit['agentRole'],
+    tool: row.tool,
+    workflowType: row.workflow_type as Commit['workflowType'],
+    loopIteration: row.loop_iteration ?? undefined,
+    ciRunId: row.ci_run_id ?? undefined,
+    pipelineName: row.pipeline_name ?? undefined,
+    message: row.message,
+    content: row.content,
+    summary: row.summary,
+    commitType: row.commit_type as Commit['commitType'],
+    gitCommitSha: row.git_commit_sha ?? undefined,
+    createdAt: new Date(row.created_at),
+  }
+}
+
+function toThread(row: ThreadRow): Thread {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    branchId: row.branch_id,
+    description: row.description,
+    status: row.status as Thread['status'],
+    workflowType: row.workflow_type as Thread['workflowType'] ?? undefined,
+    openedInCommit: row.opened_in_commit,
+    closedInCommit: row.closed_in_commit ?? undefined,
+    closedNote: row.closed_note ?? undefined,
+    createdAt: new Date(row.created_at),
+  }
+}
+
+function toClaim(row: ClaimRow): Claim {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    branchId: row.branch_id,
+    task: row.task,
+    agentId: row.agent_id,
+    role: row.role as Claim['role'],
+    claimedAt: new Date(row.claimed_at),
+    status: row.status as Claim['status'],
+    ttl: row.ttl,
+    releasedAt: row.released_at ? new Date(row.released_at) : undefined,
+  }
+}
+
+function toAgent(row: AgentRow): Agent {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    role: row.role as Agent['role'],
+    tool: row.tool,
+    workflowType: row.workflow_type as Agent['workflowType'],
+    displayName: row.display_name ?? undefined,
+    totalCommits: row.total_commits,
+    lastSeen: new Date(row.last_seen),
+    createdAt: new Date(row.created_at),
+  }
+}
+
+// ─── Queries class ───────────────────────────────────────────────────────────
+
+export class Queries {
+  private readonly db: Database
+
+  // Prepared statements (lazy init pattern via getters is avoided for simplicity;
+  // statements are prepared once in constructor)
+  private readonly stmts: {
+    insertProject: Statement
+    selectProject: Statement<[string]>
+
+    insertBranch: Statement
+    selectBranch: Statement<[string]>
+    selectBranchByGit: Statement<[string, string]>
+    selectBranches: Statement<[string]>
+    updateBranchHead: Statement<[string, string]>
+    updateBranchMerged: Statement<[number, string]>
+
+    insertCommit: Statement
+    selectCommit: Statement<[string]>
+    selectCommits: Statement<[string, number, number]>
+    selectCommitsByRole: Statement<[string, string, number]>
+    selectLastCommit: Statement<[string]>
+
+    insertThread: Statement
+    syncThread: Statement
+    closeThread: Statement<[string, string, string]>
+    selectOpenThreads: Statement<[string]>
+    selectOpenThreadsByBranch: Statement<[string]>
+    reassignThreads: Statement<[string, string]>
+
+    insertAgent: Statement
+    upsertAgent: Statement
+    selectAgent: Statement<[string]>
+    selectAgents: Statement<[string]>
+    incrementAgentCommits: Statement<[number, string]>
+
+    insertClaim: Statement
+    selectClaim: Statement<[string]>
+    listActiveClaims: Statement<[string, number]>
+    updateClaimStatus: Statement
+    releaseClaimsByAgent: Statement<[number, string, string]>
+  }
+
+  constructor(db: Database) {
+    this.db = db
+
+    this.stmts = {
+      // Projects
+      insertProject: db.prepare(`
+        INSERT INTO projects (id, name, description, github_url, created_at)
+        VALUES (@id, @name, @description, @github_url, @created_at)
+      `),
+      selectProject: db.prepare(`SELECT * FROM projects WHERE id = ?`),
+
+      // Branches
+      insertBranch: db.prepare(`
+        INSERT INTO branches
+          (id, project_id, name, git_branch, github_pr_url, parent_branch_id,
+           head_commit_id, status, created_at)
+        VALUES
+          (@id, @project_id, @name, @git_branch, @github_pr_url, @parent_branch_id,
+           @head_commit_id, @status, @created_at)
+      `),
+      selectBranch: db.prepare(`SELECT * FROM branches WHERE id = ?`),
+      selectBranchByGit: db.prepare(
+        `SELECT * FROM branches WHERE project_id = ? AND git_branch = ? LIMIT 1`
+      ),
+      selectBranches: db.prepare(`SELECT * FROM branches WHERE project_id = ? ORDER BY created_at DESC`),
+      updateBranchHead: db.prepare(`UPDATE branches SET head_commit_id = ? WHERE id = ?`),
+      updateBranchMerged: db.prepare(
+        `UPDATE branches SET status = 'merged', merged_at = ? WHERE id = ?`
+      ),
+
+      // Commits
+      insertCommit: db.prepare(`
+        INSERT INTO commits
+          (id, branch_id, parent_id, merge_source_branch_id, agent_id, agent_role,
+           tool, workflow_type, loop_iteration, ci_run_id, pipeline_name,
+           message, content, summary, commit_type, git_commit_sha, created_at)
+        VALUES
+          (@id, @branch_id, @parent_id, @merge_source_branch_id, @agent_id, @agent_role,
+           @tool, @workflow_type, @loop_iteration, @ci_run_id, @pipeline_name,
+           @message, @content, @summary, @commit_type, @git_commit_sha, @created_at)
+      `),
+      selectCommit: db.prepare(`SELECT * FROM commits WHERE id = ?`),
+      selectCommits: db.prepare(
+        `SELECT * FROM commits WHERE branch_id = ? ORDER BY created_at DESC, rowid DESC LIMIT ? OFFSET ?`
+      ),
+      selectCommitsByRole: db.prepare(
+        `SELECT * FROM commits WHERE branch_id = ? AND agent_role = ? ORDER BY created_at DESC, rowid DESC LIMIT ?`
+      ),
+      selectLastCommit: db.prepare(
+        `SELECT * FROM commits WHERE branch_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1`
+      ),
+
+      // Threads
+      insertThread: db.prepare(`
+        INSERT INTO threads
+          (id, project_id, branch_id, description, status, workflow_type,
+           opened_in_commit, created_at)
+        VALUES
+          (@id, @project_id, @branch_id, @description, 'open', @workflow_type,
+           @opened_in_commit, @created_at)
+      `),
+      syncThread: db.prepare(`
+        INSERT OR IGNORE INTO threads
+          (id, project_id, branch_id, description, status, workflow_type,
+           opened_in_commit, created_at)
+        VALUES
+          (@id, @project_id, @branch_id, @description, @status, @workflow_type,
+           @opened_in_commit, @created_at)
+      `),
+      closeThread: db.prepare(`
+        UPDATE threads
+        SET status = 'closed', closed_in_commit = ?, closed_note = ?
+        WHERE id = ?
+      `),
+      selectOpenThreads: db.prepare(
+        `SELECT * FROM threads WHERE project_id = ? AND status = 'open' ORDER BY created_at ASC`
+      ),
+      selectOpenThreadsByBranch: db.prepare(
+        `SELECT * FROM threads WHERE branch_id = ? AND status = 'open' ORDER BY created_at ASC`
+      ),
+      reassignThreads: db.prepare(
+        `UPDATE threads SET branch_id = ? WHERE branch_id = ? AND status = 'open'`
+      ),
+
+      // Agents
+      insertAgent: db.prepare(`
+        INSERT INTO agents
+          (id, project_id, role, tool, workflow_type, display_name, total_commits,
+           last_seen, created_at)
+        VALUES
+          (@id, @project_id, @role, @tool, @workflow_type, @display_name, 0,
+           @last_seen, @created_at)
+      `),
+      upsertAgent: db.prepare(`
+        INSERT INTO agents
+          (id, project_id, role, tool, workflow_type, display_name, total_commits,
+           last_seen, created_at)
+        VALUES
+          (@id, @project_id, @role, @tool, @workflow_type, @display_name, 0,
+           @last_seen, @created_at)
+        ON CONFLICT(id) DO UPDATE SET
+          role          = excluded.role,
+          tool          = excluded.tool,
+          workflow_type = excluded.workflow_type,
+          display_name  = excluded.display_name,
+          last_seen     = excluded.last_seen
+      `),
+      selectAgent: db.prepare(`SELECT * FROM agents WHERE id = ?`),
+      selectAgents: db.prepare(
+        `SELECT * FROM agents WHERE project_id = ? ORDER BY last_seen DESC`
+      ),
+      incrementAgentCommits: db.prepare(`
+        UPDATE agents SET total_commits = total_commits + 1, last_seen = ? WHERE id = ?
+      `),
+
+      // Claims
+      insertClaim: db.prepare(`
+        INSERT INTO claims
+          (id, project_id, branch_id, task, agent_id, role, claimed_at, status, ttl, released_at)
+        VALUES
+          (@id, @project_id, @branch_id, @task, @agent_id, @role, @claimed_at, @status, @ttl, NULL)
+      `),
+      selectClaim: db.prepare(`SELECT * FROM claims WHERE id = ?`),
+      listActiveClaims: db.prepare(`
+        SELECT * FROM claims
+        WHERE project_id = ?
+          AND status != 'released'
+          AND (claimed_at + ttl) > ?
+        ORDER BY claimed_at ASC
+      `),
+      updateClaimStatus: db.prepare(`
+        UPDATE claims SET status = @status, released_at = @released_at WHERE id = @id
+      `),
+      releaseClaimsByAgent: db.prepare(`
+        UPDATE claims
+        SET status = 'released', released_at = ?
+        WHERE agent_id = ? AND branch_id = ? AND status != 'released'
+      `),
+    }
+  }
+
+  // ─── Projects ────────────────────────────────────────────────────────────
+
+  insertProject(input: ProjectInput & { id: string }): Project {
+    const now = Date.now()
+    this.stmts.insertProject.run({
+      id: input.id,
+      name: input.name,
+      description: input.description ?? null,
+      github_url: input.githubUrl ?? null,
+      created_at: now,
+    })
+    return toProject({
+      id: input.id,
+      name: input.name,
+      description: input.description ?? null,
+      github_url: input.githubUrl ?? null,
+      created_at: now,
+    })
+  }
+
+  getProject(id: string): Project | null {
+    const row = this.stmts.selectProject.get(id) as ProjectRow | undefined
+    return row ? toProject(row) : null
+  }
+
+  // ─── Branches ────────────────────────────────────────────────────────────
+
+  insertBranch(input: BranchInput & { id: string }): Branch {
+    const now = Date.now()
+    this.stmts.insertBranch.run({
+      id: input.id,
+      project_id: input.projectId,
+      name: input.name,
+      git_branch: input.gitBranch,
+      github_pr_url: input.githubPrUrl ?? null,
+      parent_branch_id: input.parentBranchId ?? null,
+      head_commit_id: null,
+      status: 'active',
+      created_at: now,
+    })
+    return toBranch({
+      id: input.id,
+      project_id: input.projectId,
+      name: input.name,
+      git_branch: input.gitBranch,
+      github_pr_url: input.githubPrUrl ?? null,
+      parent_branch_id: input.parentBranchId ?? null,
+      head_commit_id: null,
+      status: 'active',
+      created_at: now,
+      merged_at: null,
+    })
+  }
+
+  getBranch(id: string): Branch | null {
+    const row = this.stmts.selectBranch.get(id) as BranchRow | undefined
+    return row ? toBranch(row) : null
+  }
+
+  getBranchByGitName(projectId: string, gitBranch: string): Branch | null {
+    const row = this.stmts.selectBranchByGit.get(projectId, gitBranch) as BranchRow | undefined
+    return row ? toBranch(row) : null
+  }
+
+  listBranches(projectId: string): Branch[] {
+    const rows = this.stmts.selectBranches.all(projectId) as BranchRow[]
+    return rows.map(toBranch)
+  }
+
+  updateBranchHead(branchId: string, commitId: string): void {
+    this.stmts.updateBranchHead.run(commitId, branchId)
+  }
+
+  markBranchMerged(branchId: string): void {
+    this.stmts.updateBranchMerged.run(Date.now(), branchId)
+  }
+
+  // ─── Commits ─────────────────────────────────────────────────────────────
+
+  insertCommit(
+    id: string,
+    input: CommitInput,
+    parentId: string | null,
+    mergeSourceBranchId: string | null = null,
+  ): Commit {
+    const now = Date.now()
+    this.stmts.insertCommit.run({
+      id,
+      branch_id: input.branchId,
+      parent_id: parentId,
+      merge_source_branch_id: mergeSourceBranchId,
+      agent_id: input.agentId,
+      agent_role: input.agentRole,
+      tool: input.tool,
+      workflow_type: input.workflowType,
+      loop_iteration: input.loopIteration ?? null,
+      ci_run_id: input.ciRunId ?? null,
+      pipeline_name: input.pipelineName ?? null,
+      message: input.message,
+      content: input.content,
+      summary: input.summary,
+      commit_type: input.commitType,
+      git_commit_sha: input.gitCommitSha ?? null,
+      created_at: now,
+    })
+    return {
+      id,
+      branchId: input.branchId,
+      parentId: parentId ?? undefined,
+      mergeSourceBranchId: mergeSourceBranchId ?? undefined,
+      agentId: input.agentId,
+      agentRole: input.agentRole,
+      tool: input.tool,
+      workflowType: input.workflowType,
+      loopIteration: input.loopIteration,
+      ciRunId: input.ciRunId,
+      pipelineName: input.pipelineName,
+      message: input.message,
+      content: input.content,
+      summary: input.summary,
+      commitType: input.commitType,
+      gitCommitSha: input.gitCommitSha,
+      createdAt: new Date(now),
+    }
+  }
+
+  getCommit(id: string): Commit | null {
+    const row = this.stmts.selectCommit.get(id) as CommitRow | undefined
+    return row ? toCommit(row) : null
+  }
+
+  listCommits(branchId: string, pagination: Pagination): Commit[] {
+    const rows = this.stmts.selectCommits.all(
+      branchId,
+      pagination.limit,
+      pagination.offset,
+    ) as CommitRow[]
+    return rows.map(toCommit)
+  }
+
+  getLastCommit(branchId: string): Commit | null {
+    const row = this.stmts.selectLastCommit.get(branchId) as CommitRow | undefined
+    return row ? toCommit(row) : null
+  }
+
+  // ─── Threads ──────────────────────────────────────────────────────────────
+
+  insertThread(
+    id: string,
+    description: string,
+    projectId: string,
+    branchId: string,
+    openedInCommit: string,
+    workflowType: string | null,
+  ): Thread {
+    const now = Date.now()
+    this.stmts.insertThread.run({
+      id,
+      project_id: projectId,
+      branch_id: branchId,
+      description,
+      workflow_type: workflowType,
+      opened_in_commit: openedInCommit,
+      created_at: now,
+    })
+    return {
+      id,
+      projectId,
+      branchId,
+      description,
+      status: 'open',
+      workflowType: workflowType as Thread['workflowType'] ?? undefined,
+      openedInCommit,
+      createdAt: new Date(now),
+    }
+  }
+
+  syncThread(thread: Thread): Thread {
+    this.stmts.syncThread.run({
+      id: thread.id,
+      project_id: thread.projectId,
+      branch_id: thread.branchId,
+      description: thread.description,
+      status: thread.status,
+      workflow_type: thread.workflowType ?? null,
+      opened_in_commit: thread.openedInCommit,
+      created_at: thread.createdAt.getTime(),
+    })
+    return thread
+  }
+
+  closeThread(threadId: string, closedInCommit: string, note: string): void {
+    this.stmts.closeThread.run(closedInCommit, note, threadId)
+  }
+
+  listOpenThreads(projectId: string): Thread[] {
+    const rows = this.stmts.selectOpenThreads.all(projectId) as ThreadRow[]
+    return rows.map(toThread)
+  }
+
+  listOpenThreadsByBranch(branchId: string): Thread[] {
+    const rows = this.stmts.selectOpenThreadsByBranch.all(branchId) as ThreadRow[]
+    return rows.map(toThread)
+  }
+
+  /** Move open threads from source branch to target (called during merge). */
+  reassignOpenThreads(fromBranchId: string, toBranchId: string): void {
+    this.stmts.reassignThreads.run(toBranchId, fromBranchId)
+  }
+
+  // ─── Agents ───────────────────────────────────────────────────────────────
+
+  upsertAgent(input: AgentInput): Agent {
+    const now = Date.now()
+    const existing = this.stmts.selectAgent.get(input.id) as AgentRow | undefined
+    this.stmts.upsertAgent.run({
+      id: input.id,
+      project_id: input.projectId,
+      role: input.role,
+      tool: input.tool,
+      workflow_type: input.workflowType,
+      display_name: input.displayName ?? null,
+      last_seen: now,
+      created_at: existing ? existing.created_at : now,
+    })
+    const row = this.stmts.selectAgent.get(input.id) as AgentRow
+    return toAgent(row)
+  }
+
+  incrementAgentCommits(agentId: string): void {
+    this.stmts.incrementAgentCommits.run(Date.now(), agentId)
+  }
+
+  listAgents(projectId: string): Agent[] {
+    const rows = this.stmts.selectAgents.all(projectId) as AgentRow[]
+    return rows.map(toAgent)
+  }
+
+  // ─── Claims ───────────────────────────────────────────────────────────────
+
+  insertClaim(id: string, projectId: string, branchId: string, input: ClaimInput): Claim {
+    const now = Date.now()
+    const ttl = input.ttl ?? 7_200_000
+    const status = input.status ?? 'proposed'
+    this.stmts.insertClaim.run({
+      id,
+      project_id: projectId,
+      branch_id: branchId,
+      task: input.task,
+      agent_id: input.agentId,
+      role: input.role,
+      claimed_at: now,
+      status,
+      ttl,
+    })
+    return toClaim(this.stmts.selectClaim.get(id) as ClaimRow)
+  }
+
+  listActiveClaims(projectId: string): Claim[] {
+    const rows = this.stmts.listActiveClaims.all(projectId, Date.now()) as ClaimRow[]
+    return rows.map(toClaim)
+  }
+
+  updateClaimStatus(id: string, status: string, releasedAt: number | null = null): void {
+    this.stmts.updateClaimStatus.run({ id, status, released_at: releasedAt })
+  }
+
+  releaseClaimsByAgent(agentId: string, branchId: string): void {
+    this.stmts.releaseClaimsByAgent.run(Date.now(), agentId, branchId)
+  }
+
+  // ─── Session snapshot helpers ─────────────────────────────────────────────
+
+  getSessionSnapshot(projectId: string, branchId: string, options?: { agentRole?: string }): SessionSnapshot {
+    // Project summary: head commit summary of the 'main' branch
+    const mainBranch = this.getBranchByGitName(projectId, 'main')
+      ?? this.getBranchByGitName(projectId, 'master')
+
+    const projectSummary = mainBranch?.headCommitId
+      ? (this.getCommit(mainBranch.headCommitId)?.summary ?? '')
+      : ''
+
+    // Branch summary: head commit summary of current branch
+    const branch = this.getBranch(branchId)
+    const branchSummary = branch?.headCommitId
+      ? (this.getCommit(branch.headCommitId)?.summary ?? '')
+      : ''
+
+    // Last 3 commits on current branch (optionally filtered by agent role)
+    const recentCommits = options?.agentRole
+      ? (this.stmts.selectCommitsByRole.all(branchId, options.agentRole, 3) as CommitRow[]).map(toCommit)
+      : this.listCommits(branchId, { limit: 3, offset: 0 })
+
+    // All open threads for the project
+    const openThreads = this.listOpenThreads(projectId)
+
+    const activeClaims = this.listActiveClaims(projectId)
+
+    return {
+      projectSummary,
+      branchName: branch?.name ?? '',
+      branchSummary,
+      recentCommits,
+      openThreads,
+      activeClaims,
+    }
+  }
+
+  // ─── Semantic search (sqlite-vec) ─────────────────────────────────────────
+
+  semanticSearch(
+    db: Database,
+    embeddingVector: Float32Array,
+    projectId: string,
+    limit: number,
+  ): SearchResult[] {
+    try {
+      // KNN query joining commit_embeddings with commits filtered by project
+      const stmt = db.prepare<[string, Float32Array, number]>(`
+        SELECT c.*, ce.distance
+        FROM commit_embeddings ce
+        JOIN commits c ON c.id = ce.commit_id
+        JOIN branches b ON b.id = c.branch_id
+        WHERE b.project_id = ?
+          AND ce.embedding MATCH ?
+          AND k = ?
+        ORDER BY ce.distance
+      `)
+      const rows = stmt.all(projectId, embeddingVector, limit) as Array<CommitRow & { distance: number }>
+      return rows.map((r) => ({
+        commit: toCommit(r),
+        score: 1 - r.distance, // cosine similarity approximation
+        matchType: 'semantic' as const,
+      }))
+    } catch {
+      // sqlite-vec not available or no embeddings indexed
+      return []
+    }
+  }
+
+  // ─── Full-text search (FTS5) ──────────────────────────────────────────────
+
+  fullTextSearch(db: Database, query: string, projectId: string): SearchResult[] {
+    try {
+      const stmt = db.prepare(`
+        SELECT c.*, bm25(commits_fts) AS score
+        FROM commits_fts
+        JOIN commits c ON c.rowid = commits_fts.rowid
+        JOIN branches b ON b.id = c.branch_id
+        WHERE b.project_id = ?
+          AND commits_fts MATCH ?
+        ORDER BY score
+        LIMIT 20
+      `)
+      const rows = stmt.all(projectId, query) as Array<CommitRow & { score: number }>
+      return rows.map((r) => ({
+        commit: toCommit(r),
+        score: Math.abs(r.score),
+        matchType: 'fulltext' as const,
+      }))
+    } catch {
+      // FTS5 migration not yet applied or query error
+      return []
+    }
+  }
+
+  // ─── Embed helpers ────────────────────────────────────────────────────────
+
+  insertEmbedding(db: Database, commitId: string, embedding: Float32Array): void {
+    try {
+      const stmt = db.prepare(
+        `INSERT OR REPLACE INTO commit_embeddings (commit_id, embedding) VALUES (?, ?)`
+      )
+      stmt.run(commitId, embedding)
+    } catch {
+      // sqlite-vec not available
+    }
+  }
+}