@rce-mcp/data-plane 0.1.0

package/src/index.ts

@@ -0,0 +1,3393 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+import { Pool, type PoolClient, type QueryResultRow } from "pg";
+import { Redis, type Redis as RedisClient } from "ioredis";
+import type { SearchContextOutput } from "@rce-mcp/contracts";
+import { openSqliteDatabase, sqliteRuntimeDriverName, type SqliteDatabase } from "./sqlite-runtime.js";
+
+export { sqliteRuntimeDriverName } from "./sqlite-runtime.js";
+
+export type RuntimeMode = "cloud" | "local" | "hybrid";
+
+export type LocalSqliteRuntime = ReturnType<typeof sqliteRuntimeDriverName>;
+
+const RUNTIME_MODES = new Set<RuntimeMode>(["cloud", "local", "hybrid"]);
+export const CLOUD_REQUIRED_ENV_VARS = [
+  "DATABASE_URL",
+  "REDIS_URL",
+  "S3_BUCKET",
+  "S3_REGION",
+  "S3_ACCESS_KEY_ID",
+  "S3_SECRET_ACCESS_KEY"
+] as const;
+
+export interface RuntimeModeResolution {
+  requested_mode: RuntimeMode;
+  effective_mode: "cloud" | "local";
+  cloud_configured: boolean;
+  missing_cloud_vars: string[];
+}
+
+export function parseRuntimeMode(value: string | undefined): RuntimeMode {
+  const normalized = (value ?? "hybrid").trim().toLowerCase();
+  if (RUNTIME_MODES.has(normalized as RuntimeMode)) {
+    return normalized as RuntimeMode;
+  }
+  throw new Error(`invalid RCE_RUNTIME_MODE: ${value ?? ""}. Expected cloud|local|hybrid.`);
+}
+
+export function missingCloudRuntimeEnvVars(env: NodeJS.ProcessEnv): string[] {
+  return CLOUD_REQUIRED_ENV_VARS.filter((key) => {
+    const value = env[key];
+    return typeof value !== "string" || value.trim() === "";
+  });
+}
+
+export function isCloudRuntimeConfigured(env: NodeJS.ProcessEnv): boolean {
+  return missingCloudRuntimeEnvVars(env).length === 0;
+}
+
+export function resolveRuntimeMode(env: NodeJS.ProcessEnv): RuntimeModeResolution {
+  const requested_mode = parseRuntimeMode(env.RCE_RUNTIME_MODE);
+  const missing_cloud_vars = missingCloudRuntimeEnvVars(env);
+  const cloud_configured = missing_cloud_vars.length === 0;
+
+  if (requested_mode === "cloud") {
+    if (!cloud_configured) {
+      throw new Error(`RCE_RUNTIME_MODE=cloud requires: ${missing_cloud_vars.join(", ")}`);
+    }
+    return {
+      requested_mode,
+      effective_mode: "cloud",
+      cloud_configured,
+      missing_cloud_vars
+    };
+  }
+
+  if (requested_mode === "local") {
+    return {
+      requested_mode,
+      effective_mode: "local",
+      cloud_configured,
+      missing_cloud_vars
+    };
+  }
+
+  return {
+    requested_mode,
+    effective_mode: cloud_configured ? "cloud" : "local",
+    cloud_configured,
+    missing_cloud_vars
+  };
+}
+
+export interface CandidateScoreWeights {
+  lexical_weight: number;
+  vector_weight: number;
+  path_match_boost: number;
+  recency_boost: number;
+  generated_penalty: number;
+}
+
+const DEFAULT_CANDIDATE_SCORE_WEIGHTS: CandidateScoreWeights = {
+  lexical_weight: 0.6,
+  vector_weight: 0.4,
+  path_match_boost: 0.2,
+  recency_boost: 0.1,
+  generated_penalty: 0.2
+};
+
+export interface WorkspaceRecord {
+  workspace_id: string;
+  tenant_id: string;
+  project_root_path: string;
+  name: string;
+}
+
+export interface ReadyIndexRecord {
+  index_id: string;
+  workspace_id: string;
+  tenant_id: string;
+  index_version: string;
+  status: "indexing" | "ready" | "failed";
+  created_at: string;
+  updated_at: string;
+}
+
+export interface IndexMetadataRecord {
+  embedding_provider: string;
+  embedding_model?: string;
+  embedding_dimensions: number;
+  embedding_version?: string;
+  chunking_strategy: "language_aware" | "sliding";
+  chunking_fallback_strategy: "sliding";
+  created_at: string;
+}
+
+export interface RankChunksInput {
+  tenant_id: string;
+  index_id: string;
+  query: string;
+  query_embedding: number[];
+  query_tokens: string[];
+  top_k: number;
+  candidate_weights?: CandidateScoreWeights;
+  filters?: {
+    language?: string;
+    path_prefix?: string;
+    glob?: string;
+  };
+}
+
+export interface RankedChunkCandidate {
+  chunk_id: string;
+  file_id: string;
+  path: string;
+  start_line: number;
+  end_line: number;
+  snippet: string;
+  language?: string;
+  generated?: boolean;
+  updated_at: string;
+  score: number;
+  lexical_score: number;
+  vector_score: number;
+  path_match: boolean;
+  recency_boosted: boolean;
+}
+
+export interface PersistedChunk {
+  chunk_id: string;
+  file_id: string;
+  path: string;
+  start_line: number;
+  end_line: number;
+  snippet: string;
+  language?: string;
+  generated?: boolean;
+  updated_at: string;
+  embedding: number[];
+}
+
+export interface PersistedFileRecord {
+  file_id: string;
+  repo_path: string;
+  content_hash: string;
+  language?: string;
+}
+
+export interface UpsertFileInput {
+  tenant_id: string;
+  index_id: string;
+  repo_path: string;
+  content_hash: string;
+  size_bytes: number;
+  language?: string;
+  warning_metadata?: Record<string, unknown>;
+  updated_at?: string;
+}
+
+export interface UpsertChunkInput {
+  start_line: number;
+  end_line: number;
+  snippet: string;
+  embedding: number[];
+  generated?: boolean;
+  updated_at?: string;
+}
+
+export interface IndexRepository {
+  migrate(): Promise<void>;
+  upsertWorkspace(input: WorkspaceRecord): Promise<void>;
+  resolveWorkspaceByProjectRoot(tenant_id: string, project_root_path: string): Promise<WorkspaceRecord | undefined>;
+  resolveWorkspaceByWorkspaceId(tenant_id: string, workspace_id: string): Promise<WorkspaceRecord | undefined>;
+  createIndexVersion(input: {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+    status?: "indexing" | "ready" | "failed";
+  }): Promise<ReadyIndexRecord>;
+  markIndexStatus(input: {
+    tenant_id: string;
+    workspace_id: string;
+    index_id: string;
+    status: "indexing" | "ready" | "failed";
+  }): Promise<void>;
+  getIndexByVersion(input: {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+  }): Promise<ReadyIndexRecord | undefined>;
+  resetIndexContent(input: {
+    tenant_id: string;
+    index_id: string;
+  }): Promise<void>;
+  getLatestReadyIndex(input: { tenant_id: string; workspace_id: string }): Promise<ReadyIndexRecord | undefined>;
+  getFilesByIndex(input: { tenant_id: string; index_id: string }): Promise<PersistedFileRecord[]>;
+  copyFileFromIndex(input: {
+    tenant_id: string;
+    source_index_id: string;
+    target_index_id: string;
+    repo_path: string;
+  }): Promise<void>;
+  upsertFile(input: UpsertFileInput): Promise<{ file_id: string }>;
+  replaceFileChunks(input: {
+    tenant_id: string;
+    file_id: string;
+    repo_path: string;
+    chunks: UpsertChunkInput[];
+  }): Promise<void>;
+  saveManifest(input: {
+    index_id: string;
+    object_key: string;
+    checksum: string;
+  }): Promise<void>;
+  saveIndexMetadata?(input: {
+    tenant_id: string;
+    index_id: string;
+    embedding_provider: string;
+    embedding_model?: string;
+    embedding_dimensions: number;
+    embedding_version?: string;
+    chunking_strategy: "language_aware" | "sliding";
+    chunking_fallback_strategy: "sliding";
+  }): Promise<void>;
+  getIndexMetadata?(input: {
+    tenant_id: string;
+    index_id: string;
+  }): Promise<IndexMetadataRecord | undefined>;
+  listChunksByIndex(input: {
+    tenant_id: string;
+    index_id: string;
+    filters?: {
+      language?: string;
+      path_prefix?: string;
+      glob?: string;
+    };
+  }): Promise<PersistedChunk[]>;
+  rankChunksByIndex?(input: RankChunksInput): Promise<RankedChunkCandidate[]>;
+}
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function parseEmbedding(raw: unknown): number[] {
+  if (Array.isArray(raw)) {
+    return raw.map((value) => Number(value));
+  }
+
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    const body = trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed;
+    if (body.length === 0) {
+      return [];
+    }
+    return body.split(",").map((value) => Number.parseFloat(value.trim()));
+  }
+
+  return [];
+}
+
+function toVectorLiteral(embedding: number[]): string {
+  return `[${embedding.join(",")}]`;
+}
+
+function toIsoString(value: unknown): string {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return new Date(String(value)).toISOString();
+}
+
+interface Queryable {
+  query<T extends QueryResultRow = QueryResultRow>(text: string, values?: readonly unknown[]): Promise<{ rows: T[] }>;
+}
+
+async function runTx<T>(pool: Pool, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    const output = await fn(client);
+    await client.query("COMMIT");
+    return output;
+  } catch (error) {
+    await client.query("ROLLBACK");
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+function ensureSqliteParent(dbPath: string): void {
+  if (dbPath === ":memory:") {
+    return;
+  }
+  mkdirSync(dirname(resolvePath(dbPath)), { recursive: true });
+}
+
+function compileGlob(glob: string): RegExp {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+}
+
+function sqliteBool(value: unknown): boolean {
+  return Number(value) === 1;
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function percentile(values: number[], p: number): number {
+  if (values.length === 0) {
+    return 0;
+  }
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1));
+  return sorted[idx] ?? 0;
+}
+
+function tokenizeForRanking(text: string): string[] {
+  const coarseTokens = text
+    .toLowerCase()
+    .split(/[^a-z0-9_./-]+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+
+  const expandedTokens: string[] = [];
+  for (const token of coarseTokens) {
+    expandedTokens.push(token);
+    for (const part of token.split(/[./_-]+/).filter(Boolean)) {
+      expandedTokens.push(part);
+    }
+  }
+
+  return [...new Set(expandedTokens)];
+}
+
+function lexicalScoreForRanking(queryTokens: string[], haystack: string): number {
+  if (queryTokens.length === 0) {
+    return 0;
+  }
+  const haystackTokens = new Set(tokenizeForRanking(haystack));
+  let overlap = 0;
+  for (const token of queryTokens) {
+    if (haystackTokens.has(token)) {
+      overlap += 1;
+    }
+  }
+  return overlap / queryTokens.length;
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length === 0 || b.length === 0) {
+    return 0;
+  }
+  const max = Math.min(a.length, b.length);
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < max; i += 1) {
+    dot += (a[i] ?? 0) * (b[i] ?? 0);
+    normA += (a[i] ?? 0) * (a[i] ?? 0);
+    normB += (b[i] ?? 0) * (b[i] ?? 0);
+  }
+  if (normA === 0 || normB === 0) {
+    return 0;
+  }
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+export class SqliteIndexRepository implements IndexRepository {
+  private readonly db: SqliteDatabase;
+
+  constructor(private readonly dbPath: string) {
+    ensureSqliteParent(dbPath);
+    this.db = openSqliteDatabase(dbPath);
+    this.db.exec("PRAGMA journal_mode = WAL;");
+    this.db.exec("PRAGMA foreign_keys = ON;");
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  async migrate(): Promise<void> {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS workspaces (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        project_root_path TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        UNIQUE (tenant_id, project_root_path)
+      );
+
+      CREATE TABLE IF NOT EXISTS indexes (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        workspace_id TEXT NOT NULL,
+        version TEXT NOT NULL,
+        status TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        UNIQUE (workspace_id, version)
+      );
+
+      CREATE TABLE IF NOT EXISTS manifests (
+        id TEXT PRIMARY KEY,
+        index_id TEXT NOT NULL,
+        object_key TEXT NOT NULL,
+        checksum TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS index_metadata (
+        index_id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        embedding_provider TEXT NOT NULL,
+        embedding_model TEXT,
+        embedding_dimensions INTEGER NOT NULL,
+        embedding_version TEXT,
+        chunking_strategy TEXT NOT NULL,
+        chunking_fallback_strategy TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS files (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        index_id TEXT NOT NULL,
+        repo_path TEXT NOT NULL,
+        content_hash TEXT NOT NULL,
+        size_bytes INTEGER NOT NULL,
+        language TEXT,
+        warning_metadata TEXT,
+        updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        UNIQUE (index_id, repo_path)
+      );
+
+      CREATE TABLE IF NOT EXISTS chunks (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        file_id TEXT NOT NULL,
+        repo_path TEXT NOT NULL,
+        start_line INTEGER NOT NULL,
+        end_line INTEGER NOT NULL,
+        text TEXT NOT NULL,
+        embedding TEXT NOT NULL,
+        generated INTEGER NOT NULL DEFAULT 0,
+        lexical_doc TEXT,
+        updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+      );
+    `);
+
+    this.db.exec("CREATE INDEX IF NOT EXISTS idx_sqlite_workspaces_tenant_path ON workspaces(tenant_id, project_root_path)");
+    this.db.exec("CREATE INDEX IF NOT EXISTS idx_sqlite_indexes_workspace_status ON indexes(workspace_id, status, created_at DESC)");
+    this.db.exec("CREATE INDEX IF NOT EXISTS idx_sqlite_index_metadata_tenant_index ON index_metadata(tenant_id, index_id)");
+    this.db.exec("CREATE INDEX IF NOT EXISTS idx_sqlite_files_index_path ON files(index_id, repo_path)");
+    this.db.exec("CREATE INDEX IF NOT EXISTS idx_sqlite_chunks_file_id ON chunks(file_id)");
+    this.db.exec("CREATE INDEX IF NOT EXISTS idx_sqlite_chunks_repo_path ON chunks(repo_path)");
+    this.db.exec("CREATE INDEX IF NOT EXISTS idx_sqlite_chunks_lexical_doc ON chunks(lexical_doc)");
+  }
+
+  async upsertWorkspace(input: WorkspaceRecord): Promise<void> {
+    this.db
+      .prepare(
+        `
+        INSERT INTO workspaces (id, tenant_id, name, project_root_path)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT (id)
+        DO UPDATE SET tenant_id = excluded.tenant_id, name = excluded.name, project_root_path = excluded.project_root_path
+        `
+      )
+      .run(input.workspace_id, input.tenant_id, input.name, input.project_root_path);
+  }
+
+  async resolveWorkspaceByProjectRoot(tenant_id: string, project_root_path: string): Promise<WorkspaceRecord | undefined> {
+    const row = this.db
+      .prepare(
+        `
+        SELECT id AS workspace_id, tenant_id, project_root_path, name
+        FROM workspaces
+        WHERE tenant_id = ? AND project_root_path = ?
+        LIMIT 1
+        `
+      )
+      .get(tenant_id, project_root_path) as
+      | {
+          workspace_id: string;
+          tenant_id: string;
+          project_root_path: string;
+          name: string;
+        }
+      | undefined;
+
+    if (!row) {
+      return undefined;
+    }
+
+    return {
+      workspace_id: row.workspace_id,
+      tenant_id: row.tenant_id,
+      project_root_path: row.project_root_path,
+      name: row.name
+    };
+  }
+
+  async resolveWorkspaceByWorkspaceId(tenant_id: string, workspace_id: string): Promise<WorkspaceRecord | undefined> {
+    const row = this.db
+      .prepare(
+        `
+        SELECT id AS workspace_id, tenant_id, project_root_path, name
+        FROM workspaces
+        WHERE tenant_id = ? AND id = ?
+        LIMIT 1
+        `
+      )
+      .get(tenant_id, workspace_id) as
+      | {
+          workspace_id: string;
+          tenant_id: string;
+          project_root_path: string;
+          name: string;
+        }
+      | undefined;
+
+    if (!row) {
+      return undefined;
+    }
+
+    return {
+      workspace_id: row.workspace_id,
+      tenant_id: row.tenant_id,
+      project_root_path: row.project_root_path,
+      name: row.name
+    };
+  }
+
+  async createIndexVersion(input: {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+    status?: "indexing" | "ready" | "failed";
+  }): Promise<ReadyIndexRecord> {
+    const index_id = `idx_${randomUUID()}`;
+    const status = input.status ?? "indexing";
+    const now = nowIso();
+
+    this.db
+      .prepare(
+        `
+        INSERT INTO indexes (id, tenant_id, workspace_id, version, status, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        `
+      )
+      .run(index_id, input.tenant_id, input.workspace_id, input.index_version, status, now, now);
+
+    return {
+      index_id,
+      workspace_id: input.workspace_id,
+      tenant_id: input.tenant_id,
+      index_version: input.index_version,
+      status,
+      created_at: now,
+      updated_at: now
+    };
+  }
+
+  async markIndexStatus(input: {
+    tenant_id: string;
+    workspace_id: string;
+    index_id: string;
+    status: "indexing" | "ready" | "failed";
+  }): Promise<void> {
+    this.db
+      .prepare(
+        `
+        UPDATE indexes
+        SET status = ?, updated_at = ?
+        WHERE id = ? AND tenant_id = ? AND workspace_id = ?
+        `
+      )
+      .run(input.status, nowIso(), input.index_id, input.tenant_id, input.workspace_id);
+  }
+
+  async getIndexByVersion(input: {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+  }): Promise<ReadyIndexRecord | undefined> {
+    const row = this.db
+      .prepare(
+        `
+        SELECT id AS index_id, workspace_id, tenant_id, version AS index_version, status, created_at, updated_at
+        FROM indexes
+        WHERE tenant_id = ? AND workspace_id = ? AND version = ?
+        LIMIT 1
+        `
+      )
+      .get(input.tenant_id, input.workspace_id, input.index_version) as
+      | {
+          index_id: string;
+          workspace_id: string;
+          tenant_id: string;
+          index_version: string;
+          status: "indexing" | "ready" | "failed";
+          created_at: string;
+          updated_at: string;
+        }
+      | undefined;
+
+    if (!row) {
+      return undefined;
+    }
+
+    return {
+      ...row,
+      created_at: toIsoString(row.created_at),
+      updated_at: toIsoString(row.updated_at)
+    };
+  }
+
+  async resetIndexContent(input: {
+    tenant_id: string;
+    index_id: string;
+  }): Promise<void> {
+    this.db.exec("BEGIN");
+    try {
+      this.db
+        .prepare(
+          `
+          DELETE FROM chunks
+          WHERE tenant_id = ? AND file_id IN (
+            SELECT id FROM files WHERE tenant_id = ? AND index_id = ?
+          )
+          `
+        )
+        .run(input.tenant_id, input.tenant_id, input.index_id);
+      this.db.prepare("DELETE FROM files WHERE tenant_id = ? AND index_id = ?").run(input.tenant_id, input.index_id);
+      this.db
+        .prepare(
+          `
+          DELETE FROM manifests
+          WHERE index_id = ?
+          `
+        )
+        .run(input.index_id);
+      this.db.exec("COMMIT");
+    } catch (error) {
+      this.db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+
+  async getLatestReadyIndex(input: { tenant_id: string; workspace_id: string }): Promise<ReadyIndexRecord | undefined> {
+    const row = this.db
+      .prepare(
+        `
+        SELECT id AS index_id, workspace_id, tenant_id, version AS index_version, status, created_at, updated_at
+        FROM indexes
+        WHERE tenant_id = ? AND workspace_id = ? AND status = 'ready'
+        ORDER BY created_at DESC
+        LIMIT 1
+        `
+      )
+      .get(input.tenant_id, input.workspace_id) as
+      | {
+          index_id: string;
+          workspace_id: string;
+          tenant_id: string;
+          index_version: string;
+          status: "indexing" | "ready" | "failed";
+          created_at: string;
+          updated_at: string;
+        }
+      | undefined;
+
+    if (!row) {
+      return undefined;
+    }
+
+    return {
+      ...row,
+      created_at: toIsoString(row.created_at),
+      updated_at: toIsoString(row.updated_at)
+    };
+  }
+
+  async getFilesByIndex(input: { tenant_id: string; index_id: string }): Promise<PersistedFileRecord[]> {
+    const rows = this.db
+      .prepare(
+        `
+        SELECT id AS file_id, repo_path, content_hash, language
+        FROM files
+        WHERE tenant_id = ? AND index_id = ?
+        `
+      )
+      .all(input.tenant_id, input.index_id) as Array<{
+      file_id: string;
+      repo_path: string;
+      content_hash: string;
+      language: string | null;
+    }>;
+
+    return rows.map((row) => ({
+      file_id: row.file_id,
+      repo_path: row.repo_path,
+      content_hash: row.content_hash,
+      ...(row.language ? { language: row.language } : {})
+    }));
+  }
+
+  async copyFileFromIndex(input: {
+    tenant_id: string;
+    source_index_id: string;
+    target_index_id: string;
+    repo_path: string;
+  }): Promise<void> {
+    this.db.exec("BEGIN");
+    try {
+      const sourceFile = this.db
+        .prepare(
+          `
+          SELECT id AS file_id, repo_path, content_hash, size_bytes, language, warning_metadata, updated_at
+          FROM files
+          WHERE tenant_id = ? AND index_id = ? AND repo_path = ?
+          LIMIT 1
+          `
+        )
+        .get(input.tenant_id, input.source_index_id, input.repo_path) as
+        | {
+            file_id: string;
+            repo_path: string;
+            content_hash: string;
+            size_bytes: number;
+            language: string | null;
+            warning_metadata: string | null;
+            updated_at: string;
+          }
+        | undefined;
+
+      if (!sourceFile) {
+        this.db.exec("COMMIT");
+        return;
+      }
+
+      const targetFileId = `fil_${randomUUID()}`;
+      this.db
+        .prepare(
+          `
+          INSERT INTO files (id, tenant_id, index_id, repo_path, content_hash, size_bytes, language, warning_metadata, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+          `
+        )
+        .run(
+          targetFileId,
+          input.tenant_id,
+          input.target_index_id,
+          sourceFile.repo_path,
+          sourceFile.content_hash,
+          sourceFile.size_bytes,
+          sourceFile.language,
+          sourceFile.warning_metadata,
+          toIsoString(sourceFile.updated_at)
+        );
+
+      const chunks = this.db
+        .prepare(
+          `
+          SELECT repo_path, start_line, end_line, text, embedding, generated, updated_at
+          FROM chunks
+          WHERE tenant_id = ? AND file_id = ?
+          `
+        )
+        .all(input.tenant_id, sourceFile.file_id) as Array<{
+        repo_path: string;
+        start_line: number;
+        end_line: number;
+        text: string;
+        embedding: string;
+        generated: number;
+        updated_at: string;
+      }>;
+
+      const insertChunk = this.db.prepare(
+        `
+        INSERT INTO chunks (id, tenant_id, file_id, repo_path, start_line, end_line, text, embedding, generated, lexical_doc, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `
+      );
+      for (const chunk of chunks) {
+        insertChunk.run(
+          `chk_${randomUUID()}`,
+          input.tenant_id,
+          targetFileId,
+          chunk.repo_path,
+          chunk.start_line,
+          chunk.end_line,
+          chunk.text,
+          chunk.embedding,
+          chunk.generated,
+          chunk.text,
+          toIsoString(chunk.updated_at)
+        );
+      }
+
+      this.db.exec("COMMIT");
+    } catch (error) {
+      this.db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+
+  async upsertFile(input: UpsertFileInput): Promise<{ file_id: string }> {
+    const existing = this.db
+      .prepare(
+        `
+        SELECT id AS file_id
+        FROM files
+        WHERE index_id = ? AND repo_path = ?
+        LIMIT 1
+        `
+      )
+      .get(input.index_id, input.repo_path) as { file_id: string } | undefined;
+
+    const warningMetadata = JSON.stringify(input.warning_metadata ?? null);
+    if (existing) {
+      this.db
+        .prepare(
+          `
+          UPDATE files
+          SET content_hash = ?, size_bytes = ?, language = ?, warning_metadata = ?, updated_at = ?
+          WHERE id = ?
+          `
+        )
+        .run(
+          input.content_hash,
+          input.size_bytes,
+          input.language ?? null,
+          warningMetadata,
+          input.updated_at ?? nowIso(),
+          existing.file_id
+        );
+      return { file_id: existing.file_id };
+    }
+
+    const file_id = `fil_${randomUUID()}`;
+    this.db
+      .prepare(
+        `
+        INSERT INTO files (id, tenant_id, index_id, repo_path, content_hash, size_bytes, language, warning_metadata, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `
+      )
+      .run(
+        file_id,
+        input.tenant_id,
+        input.index_id,
+        input.repo_path,
+        input.content_hash,
+        input.size_bytes,
+        input.language ?? null,
+        warningMetadata,
+        input.updated_at ?? nowIso()
+      );
+
+    return { file_id };
+  }
+
+  async replaceFileChunks(input: {
+    tenant_id: string;
+    file_id: string;
+    repo_path: string;
+    chunks: UpsertChunkInput[];
+  }): Promise<void> {
+    this.db.exec("BEGIN");
+    try {
+      this.db.prepare("DELETE FROM chunks WHERE tenant_id = ? AND file_id = ?").run(input.tenant_id, input.file_id);
+      const insert = this.db.prepare(
+        `
+        INSERT INTO chunks (id, tenant_id, file_id, repo_path, start_line, end_line, text, embedding, generated, lexical_doc, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `
+      );
+      for (const chunk of input.chunks) {
+        insert.run(
+          `chk_${randomUUID()}`,
+          input.tenant_id,
+          input.file_id,
+          input.repo_path,
+          chunk.start_line,
+          chunk.end_line,
+          chunk.snippet,
+          JSON.stringify(chunk.embedding),
+          chunk.generated ? 1 : 0,
+          chunk.snippet,
+          chunk.updated_at ?? nowIso()
+        );
+      }
+      this.db.exec("COMMIT");
+    } catch (error) {
+      this.db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+
+  async saveManifest(input: {
+    index_id: string;
+    object_key: string;
+    checksum: string;
+  }): Promise<void> {
+    this.db
+      .prepare(
+        `
+        INSERT INTO manifests (id, index_id, object_key, checksum, created_at)
+        VALUES (?, ?, ?, ?, ?)
+        `
+      )
+      .run(`mft_${randomUUID()}`, input.index_id, input.object_key, input.checksum, nowIso());
+  }
+
+  async saveIndexMetadata(input: {
+    tenant_id: string;
+    index_id: string;
+    embedding_provider: string;
+    embedding_model?: string;
+    embedding_dimensions: number;
+    embedding_version?: string;
+    chunking_strategy: "language_aware" | "sliding";
+    chunking_fallback_strategy: "sliding";
+  }): Promise<void> {
+    this.db
+      .prepare(
+        `
+        INSERT INTO index_metadata (
+          index_id,
+          tenant_id,
+          embedding_provider,
+          embedding_model,
+          embedding_dimensions,
+          embedding_version,
+          chunking_strategy,
+          chunking_fallback_strategy,
+          created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (index_id)
+        DO UPDATE SET
+          tenant_id = excluded.tenant_id,
+          embedding_provider = excluded.embedding_provider,
+          embedding_model = excluded.embedding_model,
+          embedding_dimensions = excluded.embedding_dimensions,
+          embedding_version = excluded.embedding_version,
+          chunking_strategy = excluded.chunking_strategy,
+          chunking_fallback_strategy = excluded.chunking_fallback_strategy
+        `
+      )
+      .run(
+        input.index_id,
+        input.tenant_id,
+        input.embedding_provider,
+        input.embedding_model ?? null,
+        input.embedding_dimensions,
+        input.embedding_version ?? null,
+        input.chunking_strategy,
+        input.chunking_fallback_strategy,
+        nowIso()
+      );
+  }
+
+  async getIndexMetadata(input: { tenant_id: string; index_id: string }): Promise<IndexMetadataRecord | undefined> {
+    const row = this.db
+      .prepare(
+        `
+        SELECT
+          embedding_provider,
+          embedding_model,
+          embedding_dimensions,
+          embedding_version,
+          chunking_strategy,
+          chunking_fallback_strategy,
+          created_at
+        FROM index_metadata
+        WHERE tenant_id = ? AND index_id = ?
+        LIMIT 1
+        `
+      )
+      .get(input.tenant_id, input.index_id) as
+      | {
+          embedding_provider: string;
+          embedding_model: string | null;
+          embedding_dimensions: number;
+          embedding_version: string | null;
+          chunking_strategy: "language_aware" | "sliding";
+          chunking_fallback_strategy: "sliding";
+          created_at: string;
+        }
+      | undefined;
+    if (!row) {
+      return undefined;
+    }
+    return {
+      embedding_provider: row.embedding_provider,
+      ...(row.embedding_model ? { embedding_model: row.embedding_model } : {}),
+      embedding_dimensions: row.embedding_dimensions,
+      ...(row.embedding_version ? { embedding_version: row.embedding_version } : {}),
+      chunking_strategy: row.chunking_strategy,
+      chunking_fallback_strategy: row.chunking_fallback_strategy,
+      created_at: toIsoString(row.created_at)
+    };
+  }
+
+  async listChunksByIndex(input: {
+    tenant_id: string;
+    index_id: string;
+    filters?: {
+      language?: string;
+      path_prefix?: string;
+      glob?: string;
+    };
+  }): Promise<PersistedChunk[]> {
+    const where: string[] = ["f.tenant_id = ?", "f.index_id = ?"];
+    const params: Array<string | number> = [input.tenant_id, input.index_id];
+
+    if (input.filters?.language) {
+      where.push("f.language = ?");
+      params.push(input.filters.language);
+    }
+
+    if (input.filters?.path_prefix) {
+      where.push("c.repo_path LIKE ?");
+      params.push(`${input.filters.path_prefix}%`);
+    }
+
+    const rows = this.db
+      .prepare(
+        `
+        SELECT
+          c.id AS chunk_id,
+          c.file_id,
+          c.repo_path AS path,
+          c.start_line,
+          c.end_line,
+          c.text AS snippet,
+          f.language,
+          c.generated,
+          c.updated_at,
+          c.embedding
+        FROM chunks c
+        INNER JOIN files f ON f.id = c.file_id
+        WHERE ${where.join(" AND ")}
+        `
+      )
+      .all(...params) as Array<{
+      chunk_id: string;
+      file_id: string;
+      path: string;
+      start_line: number;
+      end_line: number;
+      snippet: string;
+      language: string | null;
+      generated: number;
+      updated_at: string;
+      embedding: string;
+    }>;
+
+    const globRegex = input.filters?.glob ? compileGlob(input.filters.glob) : undefined;
+    return rows
+      .filter((row) => (globRegex ? globRegex.test(row.path) : true))
+      .map((row) => ({
+        chunk_id: row.chunk_id,
+        file_id: row.file_id,
+        path: row.path,
+        start_line: row.start_line,
+        end_line: row.end_line,
+        snippet: row.snippet,
+        ...(row.language ? { language: row.language } : {}),
+        ...(sqliteBool(row.generated) ? { generated: true } : {}),
+        updated_at: toIsoString(row.updated_at),
+        embedding: parseEmbedding(row.embedding)
+      }));
+  }
+
+  async rankChunksByIndex(input: RankChunksInput): Promise<RankedChunkCandidate[]> {
+    const weights = input.candidate_weights ?? DEFAULT_CANDIDATE_SCORE_WEIGHTS;
+    const where: string[] = ["f.tenant_id = ?", "f.index_id = ?"];
+    const params: Array<string | number> = [input.tenant_id, input.index_id];
+
+    if (input.filters?.language) {
+      where.push("f.language = ?");
+      params.push(input.filters.language);
+    }
+
+    if (input.filters?.path_prefix) {
+      where.push("c.repo_path LIKE ?");
+      params.push(`${input.filters.path_prefix}%`);
+    }
+
+    const rows = this.db
+      .prepare(
+        `
+        SELECT
+          c.id AS chunk_id,
+          c.file_id,
+          c.repo_path AS path,
+          c.start_line,
+          c.end_line,
+          c.text AS snippet,
+          f.language,
+          c.generated,
+          c.updated_at,
+          c.embedding
+        FROM chunks c
+        INNER JOIN files f ON f.id = c.file_id
+        WHERE ${where.join(" AND ")}
+        `
+      )
+      .all(...params) as Array<{
+      chunk_id: string;
+      file_id: string;
+      path: string;
+      start_line: number;
+      end_line: number;
+      snippet: string;
+      language: string | null;
+      generated: number;
+      updated_at: string;
+      embedding: string;
+    }>;
+
+    const globRegex = input.filters?.glob ? compileGlob(input.filters.glob) : undefined;
+    const ranked = rows
+      .filter((row) => (globRegex ? globRegex.test(row.path) : true))
+      .map((row) => {
+        const lexical = lexicalScoreForRanking(input.query_tokens, `${row.path}\n${row.snippet}`);
+        const vector = cosineSimilarity(input.query_embedding, parseEmbedding(row.embedding));
+        const pathMatch = input.query_tokens.some((token) => row.path.toLowerCase().includes(token));
+        const recencyBoost = Date.now() - new Date(toIsoString(row.updated_at)).getTime() < 14 * 24 * 3600 * 1_000;
+
+        let score = lexical * weights.lexical_weight + vector * weights.vector_weight;
+        if (pathMatch) {
+          score += weights.path_match_boost;
+        }
+        if (recencyBoost) {
+          score += weights.recency_boost;
+        }
+        if (sqliteBool(row.generated)) {
+          score -= weights.generated_penalty;
+        }
+
+        return {
+          chunk_id: row.chunk_id,
+          file_id: row.file_id,
+          path: row.path,
+          start_line: row.start_line,
+          end_line: row.end_line,
+          snippet: row.snippet,
+          ...(row.language ? { language: row.language } : {}),
+          ...(sqliteBool(row.generated) ? { generated: true } : {}),
+          updated_at: toIsoString(row.updated_at),
+          score,
+          lexical_score: lexical,
+          vector_score: vector,
+          path_match: pathMatch,
+          recency_boosted: recencyBoost
+        };
+      })
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.max(input.top_k * 4, input.top_k));
+
+    return ranked;
+  }
+}
+
+export class PostgresIndexRepository implements IndexRepository {
+  private embeddingStorage: "vector" | "array" = "vector";
+
+  constructor(
+    private readonly pool: Pool,
+    private readonly options: {
+      chunkEmbeddingDimensions?: number;
+      preferPgVector?: boolean;
+    } = {}
+  ) {}
+
+  async migrate(): Promise<void> {
+    const dimensions = this.options.chunkEmbeddingDimensions ?? 24;
+    const preferPgVector = this.options.preferPgVector ?? true;
+
+    this.embeddingStorage = "array";
+    if (preferPgVector) {
+      try {
+        await this.pool.query("CREATE EXTENSION IF NOT EXISTS vector");
+        await this.pool.query("SELECT '[1,2]'::vector");
+        this.embeddingStorage = "vector";
+      } catch {
+        this.embeddingStorage = "array";
+      }
+    }
+
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS tenants (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    `);
+
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS workspaces (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
+        name TEXT NOT NULL,
+        project_root_path TEXT NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        UNIQUE (tenant_id, project_root_path)
+      );
+    `);
+
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS indexes (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
+        workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+        version TEXT NOT NULL,
+        status TEXT NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        UNIQUE (workspace_id, version)
+      );
+    `);
+
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS manifests (
+        id TEXT PRIMARY KEY,
+        index_id TEXT NOT NULL REFERENCES indexes(id) ON DELETE CASCADE,
+        object_key TEXT NOT NULL,
+        checksum TEXT NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    `);
+
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS index_metadata (
+        index_id TEXT PRIMARY KEY REFERENCES indexes(id) ON DELETE CASCADE,
+        tenant_id TEXT NOT NULL,
+        embedding_provider TEXT NOT NULL,
+        embedding_model TEXT,
+        embedding_dimensions INTEGER NOT NULL,
+        embedding_version TEXT,
+        chunking_strategy TEXT NOT NULL,
+        chunking_fallback_strategy TEXT NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    `);
+
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS files (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
+        index_id TEXT NOT NULL REFERENCES indexes(id) ON DELETE CASCADE,
+        repo_path TEXT NOT NULL,
+        content_hash TEXT NOT NULL,
+        size_bytes INTEGER NOT NULL,
+        language TEXT,
+        warning_metadata JSONB,
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        UNIQUE (index_id, repo_path)
+      );
+    `);
+
+    const embeddingType = this.embeddingStorage === "vector" ? `vector(${dimensions})` : "DOUBLE PRECISION[]";
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS chunks (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
+        file_id TEXT NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+        repo_path TEXT NOT NULL,
+        start_line INTEGER NOT NULL,
+        end_line INTEGER NOT NULL,
+        text TEXT NOT NULL,
+        embedding ${embeddingType} NOT NULL,
+        generated BOOLEAN NOT NULL DEFAULT FALSE,
+        lexical_doc TEXT,
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    `);
+
+    await this.pool.query("CREATE INDEX IF NOT EXISTS idx_workspaces_tenant_path ON workspaces(tenant_id, project_root_path)");
+    await this.pool.query("CREATE INDEX IF NOT EXISTS idx_indexes_workspace_status ON indexes(workspace_id, status, created_at DESC)");
+    await this.pool.query("CREATE INDEX IF NOT EXISTS idx_index_metadata_tenant_index ON index_metadata(tenant_id, index_id)");
+    await this.pool.query("CREATE INDEX IF NOT EXISTS idx_files_index_path ON files(index_id, repo_path)");
+    await this.pool.query("CREATE INDEX IF NOT EXISTS idx_chunks_file_id ON chunks(file_id)");
+    await this.pool.query("CREATE INDEX IF NOT EXISTS idx_chunks_repo_path ON chunks(repo_path)");
+    await this.pool.query("CREATE INDEX IF NOT EXISTS idx_chunks_lexical_doc ON chunks(lexical_doc)");
+
+    if (this.embeddingStorage === "vector") {
+      try {
+        await this.pool.query(
+          "CREATE INDEX IF NOT EXISTS idx_chunks_embedding_vector ON chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100)"
+        );
+      } catch {
+        // Some test DBs cannot create ivfflat indexes.
+      }
+    }
+  }
+
+  async upsertWorkspace(input: WorkspaceRecord): Promise<void> {
+    await this.pool.query(
+      "INSERT INTO tenants (id, name) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING",
+      [input.tenant_id, input.tenant_id]
+    );
+
+    await this.pool.query(
+      `
+      INSERT INTO workspaces (id, tenant_id, name, project_root_path)
+      VALUES ($1, $2, $3, $4)
+      ON CONFLICT (id)
+      DO UPDATE SET tenant_id = EXCLUDED.tenant_id, name = EXCLUDED.name, project_root_path = EXCLUDED.project_root_path
+      `,
+      [input.workspace_id, input.tenant_id, input.name, input.project_root_path]
+    );
+  }
+
+  async resolveWorkspaceByProjectRoot(tenant_id: string, project_root_path: string): Promise<WorkspaceRecord | undefined> {
+    const result = await this.pool.query<{
+      workspace_id: string;
+      tenant_id: string;
+      project_root_path: string;
+      name: string;
+    }>(
+      `
+      SELECT id AS workspace_id, tenant_id, project_root_path, name
+      FROM workspaces
+      WHERE tenant_id = $1 AND project_root_path = $2
+      LIMIT 1
+      `,
+      [tenant_id, project_root_path]
+    );
+
+    const row = result.rows[0];
+    if (!row) {
+      return undefined;
+    }
+
+    return {
+      workspace_id: row.workspace_id,
+      tenant_id: row.tenant_id,
+      project_root_path: row.project_root_path,
+      name: row.name
+    };
+  }
+
+  async resolveWorkspaceByWorkspaceId(tenant_id: string, workspace_id: string): Promise<WorkspaceRecord | undefined> {
+    const result = await this.pool.query<{
+      workspace_id: string;
+      tenant_id: string;
+      project_root_path: string;
+      name: string;
+    }>(
+      `
+      SELECT id AS workspace_id, tenant_id, project_root_path, name
+      FROM workspaces
+      WHERE tenant_id = $1 AND id = $2
+      LIMIT 1
+      `,
+      [tenant_id, workspace_id]
+    );
+
+    const row = result.rows[0];
+    if (!row) {
+      return undefined;
+    }
+
+    return {
+      workspace_id: row.workspace_id,
+      tenant_id: row.tenant_id,
+      project_root_path: row.project_root_path,
+      name: row.name
+    };
+  }
+
+  async createIndexVersion(input: {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+    status?: "indexing" | "ready" | "failed";
+  }): Promise<ReadyIndexRecord> {
+    const status = input.status ?? "indexing";
+    const indexId = `idx_${randomUUID()}`;
+    const result = await this.pool.query<{
+      index_id: string;
+      workspace_id: string;
+      tenant_id: string;
+      index_version: string;
+      status: "indexing" | "ready" | "failed";
+      created_at: unknown;
+      updated_at: unknown;
+    }>(
+      `
+      INSERT INTO indexes (id, tenant_id, workspace_id, version, status)
+      VALUES ($1, $2, $3, $4, $5)
+      RETURNING id AS index_id, workspace_id, tenant_id, version AS index_version, status, created_at, updated_at
+      `,
+      [indexId, input.tenant_id, input.workspace_id, input.index_version, status]
+    );
+
+    const row = result.rows[0]!;
+    return {
+      ...row,
+      created_at: toIsoString(row.created_at),
+      updated_at: toIsoString(row.updated_at)
+    };
+  }
+
+  async markIndexStatus(input: {
+    tenant_id: string;
+    workspace_id: string;
+    index_id: string;
+    status: "indexing" | "ready" | "failed";
+  }): Promise<void> {
+    await this.pool.query(
+      `
+      UPDATE indexes
+      SET status = $4, updated_at = NOW()
+      WHERE id = $1 AND tenant_id = $2 AND workspace_id = $3
+      `,
+      [input.index_id, input.tenant_id, input.workspace_id, input.status]
+    );
+  }
+
+  async getIndexByVersion(input: {
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+  }): Promise<ReadyIndexRecord | undefined> {
+    const result = await this.pool.query<{
+      index_id: string;
+      workspace_id: string;
+      tenant_id: string;
+      index_version: string;
+      status: "indexing" | "ready" | "failed";
+      created_at: unknown;
+      updated_at: unknown;
+    }>(
+      `
+      SELECT id AS index_id, workspace_id, tenant_id, version AS index_version, status, created_at, updated_at
+      FROM indexes
+      WHERE tenant_id = $1 AND workspace_id = $2 AND version = $3
+      LIMIT 1
+      `,
+      [input.tenant_id, input.workspace_id, input.index_version]
+    );
+
+    const row = result.rows[0];
+    if (!row) {
+      return undefined;
+    }
+
+    return {
+      ...row,
+      created_at: toIsoString(row.created_at),
+      updated_at: toIsoString(row.updated_at)
+    };
+  }
+
+  async resetIndexContent(input: {
+    tenant_id: string;
+    index_id: string;
+  }): Promise<void> {
+    await runTx(this.pool, async (client) => {
+      await client.query(
+        `
+        DELETE FROM chunks
+        WHERE tenant_id = $1 AND file_id IN (
+          SELECT id FROM files WHERE tenant_id = $1 AND index_id = $2
+        )
+        `,
+        [input.tenant_id, input.index_id]
+      );
+      await client.query("DELETE FROM files WHERE tenant_id = $1 AND index_id = $2", [input.tenant_id, input.index_id]);
+      await client.query("DELETE FROM manifests WHERE index_id = $1", [input.index_id]);
+    });
+  }
+
+  async getLatestReadyIndex(input: { tenant_id: string; workspace_id: string }): Promise<ReadyIndexRecord | undefined> {
+    const result = await this.pool.query<{
+      index_id: string;
+      workspace_id: string;
+      tenant_id: string;
+      index_version: string;
+      status: "indexing" | "ready" | "failed";
+      created_at: unknown;
+      updated_at: unknown;
+    }>(
+      `
+      SELECT id AS index_id, workspace_id, tenant_id, version AS index_version, status, created_at, updated_at
+      FROM indexes
+      WHERE tenant_id = $1 AND workspace_id = $2 AND status = 'ready'
+      ORDER BY created_at DESC
+      LIMIT 1
+      `,
+      [input.tenant_id, input.workspace_id]
+    );
+
+    const row = result.rows[0];
+    if (!row) {
+      return undefined;
+    }
+    return {
+      ...row,
+      created_at: toIsoString(row.created_at),
+      updated_at: toIsoString(row.updated_at)
+    };
+  }
+
+  async getFilesByIndex(input: { tenant_id: string; index_id: string }): Promise<PersistedFileRecord[]> {
+    const result = await this.pool.query<{
+      file_id: string;
+      repo_path: string;
+      content_hash: string;
+      language: string | null;
+    }>(
+      `
+      SELECT id AS file_id, repo_path, content_hash, language
+      FROM files
+      WHERE tenant_id = $1 AND index_id = $2
+      `,
+      [input.tenant_id, input.index_id]
+    );
+
+    return result.rows.map((row) => ({
+      file_id: row.file_id,
+      repo_path: row.repo_path,
+      content_hash: row.content_hash,
+      ...(row.language ? { language: row.language } : {})
+    }));
+  }
+
+  async copyFileFromIndex(input: {
+    tenant_id: string;
+    source_index_id: string;
+    target_index_id: string;
+    repo_path: string;
+  }): Promise<void> {
+    await runTx(this.pool, async (client) => {
+      const sourceFileResult = await client.query<{
+        file_id: string;
+        repo_path: string;
+        content_hash: string;
+        size_bytes: number;
+        language: string | null;
+        warning_metadata: Record<string, unknown> | null;
+        updated_at: unknown;
+      }>(
+        `
+        SELECT id AS file_id, repo_path, content_hash, size_bytes, language, warning_metadata, updated_at
+        FROM files
+        WHERE tenant_id = $1 AND index_id = $2 AND repo_path = $3
+        LIMIT 1
+        `,
+        [input.tenant_id, input.source_index_id, input.repo_path]
+      );
+
+      const sourceFile = sourceFileResult.rows[0];
+      if (!sourceFile) {
+        return;
+      }
+
+      const targetFileId = `fil_${randomUUID()}`;
+      await client.query(
+        `
+        INSERT INTO files (id, tenant_id, index_id, repo_path, content_hash, size_bytes, language, warning_metadata, updated_at)
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9::timestamptz)
+        `,
+        [
+          targetFileId,
+          input.tenant_id,
+          input.target_index_id,
+          sourceFile.repo_path,
+          sourceFile.content_hash,
+          sourceFile.size_bytes,
+          sourceFile.language,
+          JSON.stringify(sourceFile.warning_metadata ?? null),
+          toIsoString(sourceFile.updated_at)
+        ]
+      );
+
+      const chunkRows = await client.query<{
+        repo_path: string;
+        start_line: number;
+        end_line: number;
+        text: string;
+        embedding: unknown;
+        generated: boolean;
+        updated_at: unknown;
+      }>(
+        `
+        SELECT repo_path, start_line, end_line, text, embedding, generated, updated_at
+        FROM chunks
+        WHERE tenant_id = $1 AND file_id = $2
+        `,
+        [input.tenant_id, sourceFile.file_id]
+      );
+
+      for (const chunk of chunkRows.rows) {
+        const embedding = parseEmbedding(chunk.embedding);
+        await this.insertChunk(client, {
+          tenant_id: input.tenant_id,
+          file_id: targetFileId,
+          repo_path: chunk.repo_path,
+          start_line: chunk.start_line,
+          end_line: chunk.end_line,
+          snippet: chunk.text,
+          embedding,
+          generated: chunk.generated,
+          updated_at: toIsoString(chunk.updated_at)
+        });
+      }
+    });
+  }
+
+  async upsertFile(input: UpsertFileInput): Promise<{ file_id: string }> {
+    const fileId = `fil_${randomUUID()}`;
+    const result = await this.pool.query<{ file_id: string }>(
+      `
+      INSERT INTO files (id, tenant_id, index_id, repo_path, content_hash, size_bytes, language, warning_metadata, updated_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9::timestamptz)
+      ON CONFLICT (index_id, repo_path)
+      DO UPDATE SET
+        content_hash = EXCLUDED.content_hash,
+        size_bytes = EXCLUDED.size_bytes,
+        language = EXCLUDED.language,
+        warning_metadata = EXCLUDED.warning_metadata,
+        updated_at = EXCLUDED.updated_at
+      RETURNING id AS file_id
+      `,
+      [
+        fileId,
+        input.tenant_id,
+        input.index_id,
+        input.repo_path,
+        input.content_hash,
+        input.size_bytes,
+        input.language ?? null,
+        JSON.stringify(input.warning_metadata ?? null),
+        input.updated_at ?? new Date().toISOString()
+      ]
+    );
+
+    return result.rows[0]!;
+  }
+
+  async replaceFileChunks(input: {
+    tenant_id: string;
+    file_id: string;
+    repo_path: string;
+    chunks: UpsertChunkInput[];
+  }): Promise<void> {
+    await runTx(this.pool, async (client) => {
+      await client.query("DELETE FROM chunks WHERE tenant_id = $1 AND file_id = $2", [input.tenant_id, input.file_id]);
+
+      for (const chunk of input.chunks) {
+        await this.insertChunk(client, {
+          tenant_id: input.tenant_id,
+          file_id: input.file_id,
+          repo_path: input.repo_path,
+          start_line: chunk.start_line,
+          end_line: chunk.end_line,
+          snippet: chunk.snippet,
+          embedding: chunk.embedding,
+          generated: chunk.generated,
+          updated_at: chunk.updated_at ?? new Date().toISOString()
+        });
+      }
+    });
+  }
+
+  async saveManifest(input: {
+    index_id: string;
+    object_key: string;
+    checksum: string;
+  }): Promise<void> {
+    await this.pool.query(
+      `
+      INSERT INTO manifests (id, index_id, object_key, checksum)
+      VALUES ($1, $2, $3, $4)
+      `,
+      [`mft_${randomUUID()}`, input.index_id, input.object_key, input.checksum]
+    );
+  }
+
+  async saveIndexMetadata(input: {
+    tenant_id: string;
+    index_id: string;
+    embedding_provider: string;
+    embedding_model?: string;
+    embedding_dimensions: number;
+    embedding_version?: string;
+    chunking_strategy: "language_aware" | "sliding";
+    chunking_fallback_strategy: "sliding";
+  }): Promise<void> {
+    await this.pool.query(
+      `
+      INSERT INTO index_metadata (
+        index_id,
+        tenant_id,
+        embedding_provider,
+        embedding_model,
+        embedding_dimensions,
+        embedding_version,
+        chunking_strategy,
+        chunking_fallback_strategy
+      )
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+      ON CONFLICT (index_id)
+      DO UPDATE SET
+        tenant_id = EXCLUDED.tenant_id,
+        embedding_provider = EXCLUDED.embedding_provider,
+        embedding_model = EXCLUDED.embedding_model,
+        embedding_dimensions = EXCLUDED.embedding_dimensions,
+        embedding_version = EXCLUDED.embedding_version,
+        chunking_strategy = EXCLUDED.chunking_strategy,
+        chunking_fallback_strategy = EXCLUDED.chunking_fallback_strategy
+      `,
+      [
+        input.index_id,
+        input.tenant_id,
+        input.embedding_provider,
+        input.embedding_model ?? null,
+        input.embedding_dimensions,
+        input.embedding_version ?? null,
+        input.chunking_strategy,
+        input.chunking_fallback_strategy
+      ]
+    );
+  }
+
+  async getIndexMetadata(input: { tenant_id: string; index_id: string }): Promise<IndexMetadataRecord | undefined> {
+    const result = await this.pool.query<{
+      embedding_provider: string;
+      embedding_model: string | null;
+      embedding_dimensions: number;
+      embedding_version: string | null;
+      chunking_strategy: "language_aware" | "sliding";
+      chunking_fallback_strategy: "sliding";
+      created_at: unknown;
+    }>(
+      `
+      SELECT
+        embedding_provider,
+        embedding_model,
+        embedding_dimensions,
+        embedding_version,
+        chunking_strategy,
+        chunking_fallback_strategy,
+        created_at
+      FROM index_metadata
+      WHERE tenant_id = $1 AND index_id = $2
+      LIMIT 1
+      `,
+      [input.tenant_id, input.index_id]
+    );
+    const row = result.rows[0];
+    if (!row) {
+      return undefined;
+    }
+    return {
+      embedding_provider: row.embedding_provider,
+      ...(row.embedding_model ? { embedding_model: row.embedding_model } : {}),
+      embedding_dimensions: row.embedding_dimensions,
+      ...(row.embedding_version ? { embedding_version: row.embedding_version } : {}),
+      chunking_strategy: row.chunking_strategy,
+      chunking_fallback_strategy: row.chunking_fallback_strategy,
+      created_at: toIsoString(row.created_at)
+    };
+  }
+
+  async listChunksByIndex(input: {
+    tenant_id: string;
+    index_id: string;
+    filters?: {
+      language?: string;
+      path_prefix?: string;
+      glob?: string;
+    };
+  }): Promise<PersistedChunk[]> {
+    const params: unknown[] = [input.tenant_id, input.index_id];
+    const where: string[] = ["f.tenant_id = $1", "f.index_id = $2"];
+
+    if (input.filters?.language) {
+      params.push(input.filters.language);
+      where.push(`f.language = $${params.length}`);
+    }
+
+    if (input.filters?.path_prefix) {
+      params.push(`${input.filters.path_prefix}%`);
+      where.push(`c.repo_path LIKE $${params.length}`);
+    }
+
+    if (input.filters?.glob) {
+      const regex = this.globToPostgresRegex(input.filters.glob);
+      params.push(regex);
+      where.push(`c.repo_path ~ $${params.length}`);
+    }
+
+    const result = await this.pool.query<{
+      chunk_id: string;
+      file_id: string;
+      path: string;
+      start_line: number;
+      end_line: number;
+      snippet: string;
+      language: string | null;
+      generated: boolean;
+      updated_at: unknown;
+      embedding: unknown;
+    }>(
+      `
+      SELECT
+        c.id AS chunk_id,
+        c.file_id,
+        c.repo_path AS path,
+        c.start_line,
+        c.end_line,
+        c.text AS snippet,
+        f.language,
+        c.generated,
+        c.updated_at,
+        c.embedding
+      FROM chunks c
+      INNER JOIN files f ON f.id = c.file_id
+      WHERE ${where.join(" AND ")}
+      `,
+      params
+    );
+
+    return result.rows.map((row) => ({
+      chunk_id: row.chunk_id,
+      file_id: row.file_id,
+      path: row.path,
+      start_line: row.start_line,
+      end_line: row.end_line,
+      snippet: row.snippet,
+      ...(row.language ? { language: row.language } : {}),
+      ...(row.generated ? { generated: row.generated } : {}),
+      updated_at: toIsoString(row.updated_at),
+      embedding: parseEmbedding(row.embedding)
+    }));
+  }
+
+  async rankChunksByIndex(input: RankChunksInput): Promise<RankedChunkCandidate[]> {
+    const weights = input.candidate_weights ?? DEFAULT_CANDIDATE_SCORE_WEIGHTS;
+    const params: unknown[] = [input.tenant_id, input.index_id];
+    const where: string[] = ["f.tenant_id = $1", "f.index_id = $2"];
+
+    if (input.filters?.language) {
+      params.push(input.filters.language);
+      where.push(`f.language = $${params.length}`);
+    }
+
+    if (input.filters?.path_prefix) {
+      params.push(`${input.filters.path_prefix}%`);
+      where.push(`c.repo_path LIKE $${params.length}`);
+    }
+
+    if (input.filters?.glob) {
+      const regex = this.globToPostgresRegex(input.filters.glob);
+      params.push(regex);
+      where.push(`c.repo_path ~ $${params.length}`);
+    }
+
+    if (this.embeddingStorage === "vector") {
+      const normalizedTokens = input.query_tokens.map((token) => token.toLowerCase()).filter((token) => token.length > 0);
+      params.push(normalizedTokens.length > 0 ? normalizedTokens : [""]);
+      const tokenArrayIndex = params.length;
+      params.push(toVectorLiteral(input.query_embedding));
+      const queryVectorIndex = params.length;
+      params.push(Math.max(input.top_k * 4, input.top_k));
+      const limitIndex = params.length;
+      params.push(weights.lexical_weight);
+      const lexicalWeightIndex = params.length;
+      params.push(weights.vector_weight);
+      const vectorWeightIndex = params.length;
+      params.push(weights.path_match_boost);
+      const pathMatchBoostIndex = params.length;
+      params.push(weights.recency_boost);
+      const recencyBoostIndex = params.length;
+      params.push(weights.generated_penalty);
+      const generatedPenaltyIndex = params.length;
+
+      const result = await this.pool.query<{
+        chunk_id: string;
+        file_id: string;
+        path: string;
+        start_line: number;
+        end_line: number;
+        snippet: string;
+        language: string | null;
+        generated: boolean;
+        updated_at: unknown;
+        score: number;
+        lexical_score: number;
+        vector_score: number;
+        path_match: boolean;
+        recency_boosted: boolean;
+      }>(
+        `
+        WITH scored AS (
+          SELECT
+            c.id AS chunk_id,
+            c.file_id,
+            c.repo_path AS path,
+            c.start_line,
+            c.end_line,
+            c.text AS snippet,
+            f.language,
+            c.generated,
+            c.updated_at,
+            (
+              SELECT COALESCE(COUNT(*), 0)
+              FROM unnest($${tokenArrayIndex}::text[]) AS token
+              WHERE token <> '' AND (
+                position(token in lower(c.repo_path)) > 0
+                OR position(token in lower(c.lexical_doc)) > 0
+              )
+            )::double precision / GREATEST(array_length($${tokenArrayIndex}::text[], 1), 1)::double precision AS lexical_score,
+            (1 - (c.embedding <=> $${queryVectorIndex}::vector))::double precision AS vector_score,
+            EXISTS (
+              SELECT 1
+              FROM unnest($${tokenArrayIndex}::text[]) AS token
+              WHERE token <> '' AND position(token in lower(c.repo_path)) > 0
+            ) AS path_match,
+            (c.updated_at >= NOW() - INTERVAL '14 days') AS recency_boosted
+          FROM chunks c
+          INNER JOIN files f ON f.id = c.file_id
+          WHERE ${where.join(" AND ")}
+        )
+        SELECT
+          chunk_id,
+          file_id,
+          path,
+          start_line,
+          end_line,
+          snippet,
+          language,
+          generated,
+          updated_at,
+          (lexical_score * $${lexicalWeightIndex})
+            + (vector_score * $${vectorWeightIndex})
+            + (CASE WHEN path_match THEN $${pathMatchBoostIndex} ELSE 0 END)
+            + (CASE WHEN recency_boosted THEN $${recencyBoostIndex} ELSE 0 END)
+            + (CASE WHEN generated THEN -$${generatedPenaltyIndex} ELSE 0 END) AS score,
+          lexical_score,
+          vector_score,
+          path_match,
+          recency_boosted
+        FROM scored
+        ORDER BY score DESC
+        LIMIT $${limitIndex}
+        `,
+        params
+      );
+
+      return result.rows.map((row) => ({
+        chunk_id: row.chunk_id,
+        file_id: row.file_id,
+        path: row.path,
+        start_line: row.start_line,
+        end_line: row.end_line,
+        snippet: row.snippet,
+        ...(row.language ? { language: row.language } : {}),
+        ...(row.generated ? { generated: row.generated } : {}),
+        updated_at: toIsoString(row.updated_at),
+        score: Number(row.score),
+        lexical_score: Number(row.lexical_score),
+        vector_score: Number(row.vector_score),
+        path_match: row.path_match,
+        recency_boosted: row.recency_boosted
+      }));
+    }
+
+    const rows = await this.listChunksByIndex({
+      tenant_id: input.tenant_id,
+      index_id: input.index_id,
+      filters: input.filters
+    });
+
+    return rows
+      .map((row) => {
+        const lexical = lexicalScoreForRanking(input.query_tokens, `${row.path}\n${row.snippet}`);
+        const vector = cosineSimilarity(input.query_embedding, row.embedding);
+        const pathMatch = input.query_tokens.some((token) => row.path.toLowerCase().includes(token));
+        const recencyBoost = Date.now() - new Date(row.updated_at).getTime() < 14 * 24 * 3600 * 1_000;
+
+        let score = lexical * weights.lexical_weight + vector * weights.vector_weight;
+        if (pathMatch) {
+          score += weights.path_match_boost;
+        }
+        if (recencyBoost) {
+          score += weights.recency_boost;
+        }
+        if (row.generated) {
+          score -= weights.generated_penalty;
+        }
+
+        return {
+          chunk_id: row.chunk_id,
+          file_id: row.file_id,
+          path: row.path,
+          start_line: row.start_line,
+          end_line: row.end_line,
+          snippet: row.snippet,
+          ...(row.language ? { language: row.language } : {}),
+          ...(row.generated ? { generated: true } : {}),
+          updated_at: row.updated_at,
+          score,
+          lexical_score: lexical,
+          vector_score: vector,
+          path_match: pathMatch,
+          recency_boosted: recencyBoost
+        };
+      })
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.max(input.top_k * 4, input.top_k));
+  }
+
+  private async insertChunk(
+    client: Queryable,
+    input: {
+      tenant_id: string;
+      file_id: string;
+      repo_path: string;
+      start_line: number;
+      end_line: number;
+      snippet: string;
+      embedding: number[];
+      generated?: boolean;
+      updated_at: string;
+    }
+  ): Promise<void> {
+    const embedding = this.embeddingStorage === "vector" ? toVectorLiteral(input.embedding) : input.embedding;
+    const cast = this.embeddingStorage === "vector" ? "::vector" : "::double precision[]";
+
+    await client.query(
+      `
+      INSERT INTO chunks (id, tenant_id, file_id, repo_path, start_line, end_line, text, embedding, generated, lexical_doc, updated_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8${cast}, $9, $7, $10::timestamptz)
+      `,
+      [
+        `chk_${randomUUID()}`,
+        input.tenant_id,
+        input.file_id,
+        input.repo_path,
+        input.start_line,
+        input.end_line,
+        input.snippet,
+        embedding,
+        input.generated ?? false,
+        input.updated_at
+      ]
+    );
+  }
+
+  private globToPostgresRegex(glob: string): string {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    return `^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`;
+  }
+}
+
+export function createPostgresPool(databaseUrl: string): Pool {
+  return new Pool({ connectionString: databaseUrl });
+}
+
+export interface QueryCache {
+  get(cacheKey: string): Promise<SearchContextOutput | undefined>;
+  set(cacheKey: string, value: SearchContextOutput, ttlSeconds?: number): Promise<void>;
+  invalidateWorkspace(workspace_id: string): Promise<void>;
+}
+
+export interface RedisLike {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, mode: "EX", ttlSeconds: number): Promise<unknown>;
+  keys(pattern: string): Promise<string[]>;
+  del(...keys: string[]): Promise<number>;
+  rpush(key: string, ...values: string[]): Promise<number>;
+  lrem(key: string, count: number, value: string): Promise<number>;
+  brpoplpush(source: string, destination: string, timeout: number): Promise<string | null>;
+  lrange(key: string, start: number, stop: number): Promise<string[]>;
+  llen(key: string): Promise<number>;
+  connect?(): Promise<unknown>;
+  status?: string;
+}
+
+export class RedisQueryCache implements QueryCache {
+  private readonly keyPrefix: string;
+
+  constructor(
+    private readonly redis: RedisLike,
+    options?: {
+      keyPrefix?: string;
+    }
+  ) {
+    this.keyPrefix = options?.keyPrefix ?? "rce:query_cache";
+  }
+
+  async get(cacheKey: string): Promise<SearchContextOutput | undefined> {
+    const raw = await this.redis.get(this.wrapKey(cacheKey));
+    if (!raw) {
+      return undefined;
+    }
+
+    return JSON.parse(raw) as SearchContextOutput;
+  }
+
+  async set(cacheKey: string, value: SearchContextOutput, ttlSeconds = 60): Promise<void> {
+    await this.redis.set(this.wrapKey(cacheKey), JSON.stringify(value), "EX", ttlSeconds);
+  }
+
+  async invalidateWorkspace(workspace_id: string): Promise<void> {
+    const keys = await this.redis.keys(`${this.keyPrefix}:${workspace_id}:*`);
+    if (keys.length > 0) {
+      await this.redis.del(...keys);
+    }
+  }
+
+  private wrapKey(cacheKey: string): string {
+    return `${this.keyPrefix}:${cacheKey}`;
+  }
+}
+
+export class InMemoryQueryCache implements QueryCache {
+  private readonly cache = new Map<string, { expires_at: number; value: SearchContextOutput }>();
+
+  async get(cacheKey: string): Promise<SearchContextOutput | undefined> {
+    const hit = this.cache.get(cacheKey);
+    if (!hit || hit.expires_at <= Date.now()) {
+      return undefined;
+    }
+    return hit.value;
+  }
+
+  async set(cacheKey: string, value: SearchContextOutput, ttlSeconds = 60): Promise<void> {
+    this.cache.set(cacheKey, {
+      value,
+      expires_at: Date.now() + ttlSeconds * 1_000
+    });
+  }
+
+  async invalidateWorkspace(workspace_id: string): Promise<void> {
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(`${workspace_id}:`)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+}
+
+function workspaceIdFromCacheKey(cacheKey: string): string {
+  const split = cacheKey.split(":", 1)[0];
+  return split && split.length > 0 ? split : "unknown";
+}
+
+export class SqliteQueryCache implements QueryCache {
+  private readonly db: SqliteDatabase;
+
+  constructor(private readonly dbPath: string) {
+    ensureSqliteParent(dbPath);
+    this.db = openSqliteDatabase(dbPath);
+    this.db.exec("PRAGMA journal_mode = WAL;");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS query_cache (
+        cache_key TEXT PRIMARY KEY,
+        workspace_id TEXT NOT NULL,
+        value TEXT NOT NULL,
+        expires_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_sqlite_query_cache_workspace ON query_cache(workspace_id);
+      CREATE INDEX IF NOT EXISTS idx_sqlite_query_cache_expires ON query_cache(expires_at);
+    `);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  async get(cacheKey: string): Promise<SearchContextOutput | undefined> {
+    const row = this.db
+      .prepare("SELECT value, expires_at FROM query_cache WHERE cache_key = ? LIMIT 1")
+      .get(cacheKey) as { value: string; expires_at: number } | undefined;
+    if (!row) {
+      return undefined;
+    }
+
+    if (row.expires_at <= Date.now()) {
+      this.db.prepare("DELETE FROM query_cache WHERE cache_key = ?").run(cacheKey);
+      return undefined;
+    }
+
+    return JSON.parse(row.value) as SearchContextOutput;
+  }
+
+  async set(cacheKey: string, value: SearchContextOutput, ttlSeconds = 60): Promise<void> {
+    const expires_at = Date.now() + ttlSeconds * 1_000;
+    this.db
+      .prepare(
+        `
+        INSERT INTO query_cache (cache_key, workspace_id, value, expires_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT (cache_key)
+        DO UPDATE SET workspace_id = excluded.workspace_id, value = excluded.value, expires_at = excluded.expires_at
+        `
+      )
+      .run(cacheKey, workspaceIdFromCacheKey(cacheKey), JSON.stringify(value), expires_at);
+  }
+
+  async invalidateWorkspace(workspace_id: string): Promise<void> {
+    this.db.prepare("DELETE FROM query_cache WHERE workspace_id = ?").run(workspace_id);
+  }
+}
+
+export interface IndexJobPayload {
+  job_id: string;
+  tenant_id: string;
+  workspace_id: string;
+  index_version: string;
+  manifest_key: string;
+  attempts: number;
+  enqueued_at: string;
+  claimed_at?: string;
+}
+
+interface FailedIndexJobPayload extends IndexJobPayload {
+  failed_at: string;
+  last_error: string;
+}
+
+export interface UsageMeteringRecordInput {
+  tenant_id: string;
+  workspace_id?: string;
+  tool_name: string;
+  trace_id: string;
+  status: "success" | "error";
+  latency_ms: number;
+  result_count: number;
+  units: number;
+  created_at?: string;
+}
+
+export interface AuditEventInput {
+  tenant_id: string;
+  subject: string;
+  action: string;
+  resource: string;
+  status: "success" | "error" | "denied";
+  trace_id: string;
+  details?: Record<string, unknown>;
+  created_at?: string;
+}
+
+export interface UsageSummary {
+  tenant_id: string;
+  tool_name: string;
+  request_count: number;
+  error_count: number;
+  total_units: number;
+  p95_latency_ms: number;
+  last_seen_at?: string;
+}
+
+export interface AuditEventRecord {
+  event_id: string;
+  tenant_id: string;
+  subject: string;
+  action: string;
+  resource: string;
+  status: "success" | "error" | "denied";
+  trace_id: string;
+  details?: Record<string, unknown>;
+  created_at: string;
+}
+
+export interface UsageMeterStore {
+  migrate(): Promise<void>;
+  recordUsage(input: UsageMeteringRecordInput): Promise<void>;
+  recordAuditEvent(input: AuditEventInput): Promise<void>;
+  listUsageSummary(input?: {
+    tenant_id?: string;
+    from?: string;
+    to?: string;
+  }): Promise<UsageSummary[]>;
+  listAuditEvents(input?: {
+    tenant_id?: string;
+    limit?: number;
+  }): Promise<AuditEventRecord[]>;
+}
+
+export interface ClaimedIndexJob {
+  raw: string;
+  payload: IndexJobPayload;
+}
+
+export interface IndexJobQueue {
+  enqueue(job: Omit<IndexJobPayload, "job_id" | "attempts" | "enqueued_at"> & { job_id?: string }): Promise<IndexJobPayload>;
+  claimNext(timeoutSeconds?: number): Promise<ClaimedIndexJob | undefined>;
+  ack(claimed: ClaimedIndexJob): Promise<void>;
+  retryOrDeadLetter(claimed: ClaimedIndexJob, errorMessage: string): Promise<void>;
+  reclaimOrphaned(maxClaimAgeSeconds?: number): Promise<number>;
+  deadLetterCount(): Promise<number>;
+  pendingCount(): Promise<number>;
+  processingCount(): Promise<number>;
+  listDeadLetters(): Promise<FailedIndexJobPayload[]>;
+}
+
+export class RedisIndexJobQueue implements IndexJobQueue {
+  private readonly pendingKey: string;
+  private readonly processingKey: string;
+  private readonly deadLetterKey: string;
+  private readonly maxAttempts: number;
+  private readonly leasePrefix: string;
+  private readonly claimLeaseSeconds: number;
+  private readonly reconnectRetries: number;
+  private readonly reconnectDelayMs: number;
+
+  constructor(
+    private readonly redis: RedisLike,
+    options?: {
+      keyPrefix?: string;
+      maxAttempts?: number;
+      claimLeaseSeconds?: number;
+      reconnectRetries?: number;
+      reconnectDelayMs?: number;
+    }
+  ) {
+    const prefix = options?.keyPrefix ?? "rce:index_jobs";
+    this.pendingKey = `${prefix}:pending`;
+    this.processingKey = `${prefix}:processing`;
+    this.deadLetterKey = `${prefix}:dead`;
+    this.leasePrefix = `${prefix}:lease`;
+    this.maxAttempts = options?.maxAttempts ?? 3;
+    this.claimLeaseSeconds = Math.max(5, options?.claimLeaseSeconds ?? 120);
+    this.reconnectRetries = Math.max(0, options?.reconnectRetries ?? 1);
+    this.reconnectDelayMs = Math.max(0, options?.reconnectDelayMs ?? 100);
+  }
+
+  async enqueue(job: Omit<IndexJobPayload, "job_id" | "attempts" | "enqueued_at"> & { job_id?: string }): Promise<IndexJobPayload> {
+    const payload: IndexJobPayload = {
+      job_id: job.job_id ?? `job_${randomUUID()}`,
+      tenant_id: job.tenant_id,
+      workspace_id: job.workspace_id,
+      index_version: job.index_version,
+      manifest_key: job.manifest_key,
+      attempts: 0,
+      enqueued_at: new Date().toISOString()
+    };
+
+    await this.runRedisOperation(() => this.redis.rpush(this.pendingKey, JSON.stringify(payload)));
+    return payload;
+  }
+
+  async claimNext(timeoutSeconds = 1): Promise<ClaimedIndexJob | undefined> {
+    const raw = await this.runRedisOperation(() => this.redis.brpoplpush(this.pendingKey, this.processingKey, timeoutSeconds));
+    if (!raw) {
+      return undefined;
+    }
+
+    const payload = JSON.parse(raw) as IndexJobPayload;
+    const claimedAt = nowIso();
+    payload.claimed_at = claimedAt;
+    const claimedRaw = JSON.stringify(payload);
+
+    if (claimedRaw !== raw) {
+      await this.runRedisOperation(() => this.redis.lrem(this.processingKey, 1, raw));
+      await this.runRedisOperation(() => this.redis.rpush(this.processingKey, claimedRaw));
+    }
+
+    await this.runRedisOperation(() =>
+      this.redis.set(this.leaseKey(payload.job_id), claimedAt, "EX", this.claimLeaseSeconds)
+    );
+    return { raw: claimedRaw, payload };
+  }
+
+  async ack(claimed: ClaimedIndexJob): Promise<void> {
+    await this.runRedisOperation(() => this.redis.lrem(this.processingKey, 1, claimed.raw));
+    await this.runRedisOperation(() => this.redis.del(this.leaseKey(claimed.payload.job_id)));
+  }
+
+  async retryOrDeadLetter(claimed: ClaimedIndexJob, errorMessage: string): Promise<void> {
+    await this.runRedisOperation(() => this.redis.lrem(this.processingKey, 1, claimed.raw));
+    await this.runRedisOperation(() => this.redis.del(this.leaseKey(claimed.payload.job_id)));
+    const attempts = claimed.payload.attempts + 1;
+
+    if (attempts >= this.maxAttempts) {
+      const failed: FailedIndexJobPayload = {
+        ...claimed.payload,
+        attempts,
+        failed_at: new Date().toISOString(),
+        last_error: errorMessage
+      };
+      await this.runRedisOperation(() => this.redis.rpush(this.deadLetterKey, JSON.stringify(failed)));
+      return;
+    }
+
+    const retryPayload: IndexJobPayload = {
+      ...claimed.payload,
+      attempts,
+      claimed_at: undefined
+    };
+    await this.runRedisOperation(() => this.redis.rpush(this.pendingKey, JSON.stringify(retryPayload)));
+  }
+
+  async reclaimOrphaned(maxClaimAgeSeconds = this.claimLeaseSeconds): Promise<number> {
+    const processing = await this.runRedisOperation(() => this.redis.lrange(this.processingKey, 0, -1));
+    let reclaimed = 0;
+    const ageThresholdMs = Math.max(1, maxClaimAgeSeconds) * 1_000;
+
+    for (const raw of processing) {
+      const payload = JSON.parse(raw) as IndexJobPayload;
+      const lease = await this.runRedisOperation(() => this.redis.get(this.leaseKey(payload.job_id)));
+      const claimedAtMs = payload.claimed_at ? new Date(payload.claimed_at).getTime() : 0;
+      const staleByAge = claimedAtMs > 0 && Date.now() - claimedAtMs >= ageThresholdMs;
+
+      if (lease && !staleByAge) {
+        continue;
+      }
+
+      if (payload.claimed_at && !staleByAge) {
+        continue;
+      }
+
+      const removed = await this.runRedisOperation(() => this.redis.lrem(this.processingKey, 1, raw));
+      if (removed > 0) {
+        const retryPayload: IndexJobPayload = {
+          ...payload,
+          claimed_at: undefined
+        };
+        await this.runRedisOperation(() => this.redis.rpush(this.pendingKey, JSON.stringify(retryPayload)));
+        reclaimed += 1;
+      }
+    }
+
+    return reclaimed;
+  }
+
+  async deadLetterCount(): Promise<number> {
+    return this.runRedisOperation(() => this.redis.llen(this.deadLetterKey));
+  }
+
+  async pendingCount(): Promise<number> {
+    return this.runRedisOperation(() => this.redis.llen(this.pendingKey));
+  }
+
+  async processingCount(): Promise<number> {
+    return this.runRedisOperation(() => this.redis.llen(this.processingKey));
+  }
+
+  async listDeadLetters(): Promise<FailedIndexJobPayload[]> {
+    const rows = await this.runRedisOperation(() => this.redis.lrange(this.deadLetterKey, 0, -1));
+    return rows.map((row) => JSON.parse(row) as FailedIndexJobPayload);
+  }
+
+  private async runRedisOperation<T>(operation: () => Promise<T>): Promise<T> {
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        return await operation();
+      } catch (error) {
+        const finalAttempt = attempt >= this.reconnectRetries;
+        if (finalAttempt || !this.isRecoverableRedisError(error)) {
+          throw error;
+        }
+
+        try {
+          if (typeof this.redis.connect === "function") {
+            await this.redis.connect();
+          }
+        } catch {
+          // Ignore reconnect failures here; next operation attempt will fail if redis is still unavailable.
+        }
+
+        if (this.reconnectDelayMs > 0) {
+          await waitMs(this.reconnectDelayMs);
+        }
+      }
+    }
+  }
+
+  private isRecoverableRedisError(error: unknown): boolean {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    const message = error.message.toLowerCase();
+    return (
+      message.includes("connection") ||
+      message.includes("socket") ||
+      message.includes("econnrefused") ||
+      message.includes("econnreset") ||
+      message.includes("closed")
+    );
+  }
+
+  private leaseKey(jobId: string): string {
+    return `${this.leasePrefix}:${jobId}`;
+  }
+}
+
+export class InMemoryIndexJobQueue implements IndexJobQueue {
+  private readonly pending: IndexJobPayload[] = [];
+  private readonly dead: FailedIndexJobPayload[] = [];
+  private readonly processing = new Map<string, IndexJobPayload>();
+  private readonly maxAttempts: number;
+
+  constructor(options?: { maxAttempts?: number }) {
+    this.maxAttempts = options?.maxAttempts ?? 3;
+  }
+
+  async enqueue(job: Omit<IndexJobPayload, "job_id" | "attempts" | "enqueued_at"> & { job_id?: string }): Promise<IndexJobPayload> {
+    const payload: IndexJobPayload = {
+      job_id: job.job_id ?? `job_${randomUUID()}`,
+      tenant_id: job.tenant_id,
+      workspace_id: job.workspace_id,
+      index_version: job.index_version,
+      manifest_key: job.manifest_key,
+      attempts: 0,
+      enqueued_at: new Date().toISOString()
+    };
+    this.pending.push(payload);
+    return payload;
+  }
+
+  async claimNext(): Promise<ClaimedIndexJob | undefined> {
+    const next = this.pending.shift();
+    if (!next) {
+      return undefined;
+    }
+
+    const claimed: IndexJobPayload = {
+      ...next,
+      claimed_at: nowIso()
+    };
+    this.processing.set(claimed.job_id, claimed);
+
+    return {
+      payload: claimed,
+      raw: JSON.stringify(next)
+    };
+  }
+
+  async ack(claimed: ClaimedIndexJob): Promise<void> {
+    this.processing.delete(claimed.payload.job_id);
+    return;
+  }
+
+  async retryOrDeadLetter(claimed: ClaimedIndexJob, errorMessage: string): Promise<void> {
+    this.processing.delete(claimed.payload.job_id);
+    const attempts = claimed.payload.attempts + 1;
+    if (attempts >= this.maxAttempts) {
+      this.dead.push({
+        ...claimed.payload,
+        attempts,
+        failed_at: new Date().toISOString(),
+        last_error: errorMessage
+      });
+      return;
+    }
+
+    this.pending.push({
+      ...claimed.payload,
+      attempts,
+      claimed_at: undefined
+    });
+  }
+
+  async reclaimOrphaned(maxClaimAgeSeconds = 120): Promise<number> {
+    const cutoff = Date.now() - Math.max(1, maxClaimAgeSeconds) * 1_000;
+    let reclaimed = 0;
+
+    for (const [jobId, payload] of this.processing.entries()) {
+      const claimedAt = payload.claimed_at ? new Date(payload.claimed_at).getTime() : 0;
+      if (claimedAt > cutoff) {
+        continue;
+      }
+      this.processing.delete(jobId);
+      this.pending.push({
+        ...payload,
+        claimed_at: undefined
+      });
+      reclaimed += 1;
+    }
+    return reclaimed;
+  }
+
+  async deadLetterCount(): Promise<number> {
+    return this.dead.length;
+  }
+
+  async pendingCount(): Promise<number> {
+    return this.pending.length;
+  }
+
+  async processingCount(): Promise<number> {
+    return this.processing.size;
+  }
+
+  async listDeadLetters(): Promise<FailedIndexJobPayload[]> {
+    return [...this.dead];
+  }
+}
+
+function waitMs(delay: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, delay));
+}
+
+export class SqliteIndexJobQueue implements IndexJobQueue {
+  private readonly db: SqliteDatabase;
+  private readonly maxAttempts: number;
+  private readonly claimTtlSeconds: number;
+
+  constructor(
+    private readonly dbPath: string,
+    options?: {
+      maxAttempts?: number;
+      claimTtlSeconds?: number;
+    }
+  ) {
+    ensureSqliteParent(dbPath);
+    this.db = openSqliteDatabase(dbPath);
+    this.db.exec("PRAGMA journal_mode = WAL;");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS index_jobs (
+        job_id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        workspace_id TEXT NOT NULL,
+        index_version TEXT NOT NULL,
+        manifest_key TEXT NOT NULL,
+        attempts INTEGER NOT NULL,
+        enqueued_at TEXT NOT NULL,
+        status TEXT NOT NULL,
+        claimed_at TEXT,
+        failed_at TEXT,
+        last_error TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_sqlite_index_jobs_status_enqueued ON index_jobs(status, enqueued_at);
+      CREATE INDEX IF NOT EXISTS idx_sqlite_index_jobs_status_failed ON index_jobs(status, failed_at);
+    `);
+    this.maxAttempts = options?.maxAttempts ?? 3;
+    this.claimTtlSeconds = Math.max(5, options?.claimTtlSeconds ?? 120);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  async enqueue(job: Omit<IndexJobPayload, "job_id" | "attempts" | "enqueued_at"> & { job_id?: string }): Promise<IndexJobPayload> {
+    const payload: IndexJobPayload = {
+      job_id: job.job_id ?? `job_${randomUUID()}`,
+      tenant_id: job.tenant_id,
+      workspace_id: job.workspace_id,
+      index_version: job.index_version,
+      manifest_key: job.manifest_key,
+      attempts: 0,
+      enqueued_at: nowIso()
+    };
+
+    this.db
+      .prepare(
+        `
+        INSERT INTO index_jobs (job_id, tenant_id, workspace_id, index_version, manifest_key, attempts, enqueued_at, status)
+        VALUES (?, ?, ?, ?, ?, ?, ?, 'pending')
+        `
+      )
+      .run(
+        payload.job_id,
+        payload.tenant_id,
+        payload.workspace_id,
+        payload.index_version,
+        payload.manifest_key,
+        payload.attempts,
+        payload.enqueued_at
+      );
+    return payload;
+  }
+
+  async claimNext(timeoutSeconds = 1): Promise<ClaimedIndexJob | undefined> {
+    const deadline = Date.now() + Math.max(0, timeoutSeconds) * 1_000;
+    do {
+      const claimed = this.claimNextImmediate();
+      if (claimed) {
+        return claimed;
+      }
+      if (timeoutSeconds <= 0) {
+        break;
+      }
+      await waitMs(50);
+    } while (Date.now() <= deadline);
+    return undefined;
+  }
+
+  async ack(claimed: ClaimedIndexJob): Promise<void> {
+    this.db.prepare("DELETE FROM index_jobs WHERE job_id = ?").run(claimed.payload.job_id);
+  }
+
+  async retryOrDeadLetter(claimed: ClaimedIndexJob, errorMessage: string): Promise<void> {
+    const attempts = claimed.payload.attempts + 1;
+    if (attempts >= this.maxAttempts) {
+      this.db
+        .prepare(
+          `
+          UPDATE index_jobs
+          SET attempts = ?, status = 'dead', failed_at = ?, last_error = ?, claimed_at = NULL
+          WHERE job_id = ?
+          `
+        )
+        .run(attempts, nowIso(), errorMessage, claimed.payload.job_id);
+      return;
+    }
+
+    this.db
+      .prepare(
+        `
+        UPDATE index_jobs
+        SET attempts = ?, status = 'pending', last_error = ?, claimed_at = NULL
+        WHERE job_id = ?
+        `
+      )
+      .run(attempts, errorMessage, claimed.payload.job_id);
+  }
+
+  async reclaimOrphaned(maxClaimAgeSeconds = this.claimTtlSeconds): Promise<number> {
+    const cutoff = new Date(Date.now() - Math.max(1, maxClaimAgeSeconds) * 1_000).toISOString();
+    const updated = this.db
+      .prepare(
+        `
+        UPDATE index_jobs
+        SET status = 'pending', claimed_at = NULL, last_error = COALESCE(last_error, 'reclaimed orphaned in-flight job')
+        WHERE status = 'processing' AND claimed_at IS NOT NULL AND claimed_at < ?
+        `
+      )
+      .run(cutoff);
+    return Number(updated.changes ?? 0);
+  }
+
+  async deadLetterCount(): Promise<number> {
+    const row = this.db.prepare("SELECT COUNT(*) AS count FROM index_jobs WHERE status = 'dead'").get() as { count: number };
+    return Number(row.count);
+  }
+
+  async pendingCount(): Promise<number> {
+    const row = this.db.prepare("SELECT COUNT(*) AS count FROM index_jobs WHERE status = 'pending'").get() as { count: number };
+    return Number(row.count);
+  }
+
+  async processingCount(): Promise<number> {
+    const row = this.db.prepare("SELECT COUNT(*) AS count FROM index_jobs WHERE status = 'processing'").get() as { count: number };
+    return Number(row.count);
+  }
+
+  async listDeadLetters(): Promise<FailedIndexJobPayload[]> {
+    const rows = this.db
+      .prepare(
+        `
+        SELECT job_id, tenant_id, workspace_id, index_version, manifest_key, attempts, enqueued_at, failed_at, last_error
+        FROM index_jobs
+        WHERE status = 'dead'
+        ORDER BY failed_at DESC
+        `
+      )
+      .all() as Array<{
+      job_id: string;
+      tenant_id: string;
+      workspace_id: string;
+      index_version: string;
+      manifest_key: string;
+      attempts: number;
+      enqueued_at: string;
+      failed_at: string;
+      last_error: string;
+    }>;
+    return rows.map((row) => ({
+      job_id: row.job_id,
+      tenant_id: row.tenant_id,
+      workspace_id: row.workspace_id,
+      index_version: row.index_version,
+      manifest_key: row.manifest_key,
+      attempts: Number(row.attempts),
+      enqueued_at: row.enqueued_at,
+      failed_at: row.failed_at,
+      last_error: row.last_error
+    }));
+  }
+
+  private claimNextImmediate(): ClaimedIndexJob | undefined {
+    const row = this.db
+      .prepare(
+        `
+        SELECT job_id, tenant_id, workspace_id, index_version, manifest_key, attempts, enqueued_at
+        FROM index_jobs
+        WHERE status = 'pending'
+        ORDER BY enqueued_at ASC
+        LIMIT 1
+        `
+      )
+      .get() as
+      | {
+          job_id: string;
+          tenant_id: string;
+          workspace_id: string;
+          index_version: string;
+          manifest_key: string;
+          attempts: number;
+          enqueued_at: string;
+        }
+      | undefined;
+
+    if (!row) {
+      return undefined;
+    }
+
+    const claimedAt = nowIso();
+    const changed = this.db
+      .prepare(
+        `
+        UPDATE index_jobs
+        SET status = 'processing', claimed_at = ?
+        WHERE job_id = ? AND status = 'pending'
+        `
+      )
+      .run(claimedAt, row.job_id);
+
+    if (Number(changed.changes) !== 1) {
+      return undefined;
+    }
+
+    const payload: IndexJobPayload = {
+      job_id: row.job_id,
+      tenant_id: row.tenant_id,
+      workspace_id: row.workspace_id,
+      index_version: row.index_version,
+      manifest_key: row.manifest_key,
+      attempts: Number(row.attempts),
+      enqueued_at: row.enqueued_at,
+      claimed_at: claimedAt
+    };
+
+    return {
+      payload,
+      raw: JSON.stringify(payload)
+    };
+  }
+}
+
+export class InMemoryUsageMeterStore implements UsageMeterStore {
+  private readonly usage: UsageMeteringRecordInput[] = [];
+  private readonly audit: AuditEventRecord[] = [];
+
+  async migrate(): Promise<void> {
+    return;
+  }
+
+  async recordUsage(input: UsageMeteringRecordInput): Promise<void> {
+    this.usage.push({
+      ...input,
+      created_at: input.created_at ?? nowIso()
+    });
+  }
+
+  async recordAuditEvent(input: AuditEventInput): Promise<void> {
+    this.audit.push({
+      event_id: `aud_${randomUUID()}`,
+      tenant_id: input.tenant_id,
+      subject: input.subject,
+      action: input.action,
+      resource: input.resource,
+      status: input.status,
+      trace_id: input.trace_id,
+      ...(input.details ? { details: input.details } : {}),
+      created_at: input.created_at ?? nowIso()
+    });
+  }
+
+  async listUsageSummary(input?: {
+    tenant_id?: string;
+    from?: string;
+    to?: string;
+  }): Promise<UsageSummary[]> {
+    const fromMs = input?.from ? new Date(input.from).getTime() : Number.NEGATIVE_INFINITY;
+    const toMs = input?.to ? new Date(input.to).getTime() : Number.POSITIVE_INFINITY;
+    const rows = this.usage.filter((row) => {
+      if (input?.tenant_id && row.tenant_id !== input.tenant_id) {
+        return false;
+      }
+      const ts = new Date(row.created_at ?? nowIso()).getTime();
+      return ts >= fromMs && ts <= toMs;
+    });
+
+    const grouped = new Map<
+      string,
+      { tenant_id: string; tool_name: string; request_count: number; error_count: number; total_units: number; latencies: number[]; last: string }
+    >();
+    for (const row of rows) {
+      const key = `${row.tenant_id}:${row.tool_name}`;
+      const existing =
+        grouped.get(key) ??
+        {
+          tenant_id: row.tenant_id,
+          tool_name: row.tool_name,
+          request_count: 0,
+          error_count: 0,
+          total_units: 0,
+          latencies: [],
+          last: row.created_at ?? nowIso()
+        };
+      existing.request_count += 1;
+      existing.error_count += row.status === "error" ? 1 : 0;
+      existing.total_units += row.units;
+      existing.latencies.push(row.latency_ms);
+      if ((row.created_at ?? nowIso()) > existing.last) {
+        existing.last = row.created_at ?? nowIso();
+      }
+      grouped.set(key, existing);
+    }
+
+    return [...grouped.values()].map((row) => ({
+      tenant_id: row.tenant_id,
+      tool_name: row.tool_name,
+      request_count: row.request_count,
+      error_count: row.error_count,
+      total_units: row.total_units,
+      p95_latency_ms: percentile(row.latencies, 0.95),
+      last_seen_at: row.last
+    }));
+  }
+
+  async listAuditEvents(input?: {
+    tenant_id?: string;
+    limit?: number;
+  }): Promise<AuditEventRecord[]> {
+    const limit = Math.max(1, input?.limit ?? 100);
+    return this.audit
+      .filter((row) => (input?.tenant_id ? row.tenant_id === input.tenant_id : true))
+      .sort((a, b) => b.created_at.localeCompare(a.created_at))
+      .slice(0, limit);
+  }
+}
+
+export class SqliteUsageMeterStore implements UsageMeterStore {
+  private readonly db: SqliteDatabase;
+
+  constructor(private readonly dbPath: string) {
+    ensureSqliteParent(dbPath);
+    this.db = openSqliteDatabase(dbPath);
+    this.db.exec("PRAGMA journal_mode = WAL;");
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  async migrate(): Promise<void> {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS usage_metering (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        workspace_id TEXT,
+        tool_name TEXT NOT NULL,
+        trace_id TEXT NOT NULL,
+        status TEXT NOT NULL,
+        latency_ms INTEGER NOT NULL,
+        result_count INTEGER NOT NULL,
+        units INTEGER NOT NULL,
+        created_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_usage_metering_tenant_created ON usage_metering(tenant_id, created_at DESC);
+      CREATE TABLE IF NOT EXISTS audit_events (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        action TEXT NOT NULL,
+        resource TEXT NOT NULL,
+        status TEXT NOT NULL,
+        trace_id TEXT NOT NULL,
+        details TEXT,
+        created_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_audit_events_tenant_created ON audit_events(tenant_id, created_at DESC);
+    `);
+  }
+
+  async recordUsage(input: UsageMeteringRecordInput): Promise<void> {
+    this.db
+      .prepare(
+        `
+        INSERT INTO usage_metering
+          (id, tenant_id, workspace_id, tool_name, trace_id, status, latency_ms, result_count, units, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `
+      )
+      .run(
+        `usg_${randomUUID()}`,
+        input.tenant_id,
+        input.workspace_id ?? null,
+        input.tool_name,
+        input.trace_id,
+        input.status,
+        Math.max(0, Math.floor(input.latency_ms)),
+        Math.max(0, Math.floor(input.result_count)),
+        Math.max(0, Math.floor(input.units)),
+        input.created_at ?? nowIso()
+      );
+  }
+
+  async recordAuditEvent(input: AuditEventInput): Promise<void> {
+    this.db
+      .prepare(
+        `
+        INSERT INTO audit_events
+          (id, tenant_id, subject, action, resource, status, trace_id, details, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `
+      )
+      .run(
+        `aud_${randomUUID()}`,
+        input.tenant_id,
+        input.subject,
+        input.action,
+        input.resource,
+        input.status,
+        input.trace_id,
+        input.details ? JSON.stringify(input.details) : null,
+        input.created_at ?? nowIso()
+      );
+  }
+
+  async listUsageSummary(input?: {
+    tenant_id?: string;
+    from?: string;
+    to?: string;
+  }): Promise<UsageSummary[]> {
+    const where: string[] = [];
+    const params: Array<string | number> = [];
+    if (input?.tenant_id) {
+      where.push("tenant_id = ?");
+      params.push(input.tenant_id);
+    }
+    if (input?.from) {
+      where.push("created_at >= ?");
+      params.push(input.from);
+    }
+    if (input?.to) {
+      where.push("created_at <= ?");
+      params.push(input.to);
+    }
+
+    const rows = this.db
+      .prepare(
+        `
+        SELECT tenant_id, tool_name, status, latency_ms, units, created_at
+        FROM usage_metering
+        ${where.length > 0 ? `WHERE ${where.join(" AND ")}` : ""}
+        `
+      )
+      .all(...params) as Array<{
+      tenant_id: string;
+      tool_name: string;
+      status: string;
+      latency_ms: number;
+      units: number;
+      created_at: string;
+    }>;
+
+    const grouped = new Map<
+      string,
+      { tenant_id: string; tool_name: string; request_count: number; error_count: number; total_units: number; latencies: number[]; last: string }
+    >();
+    for (const row of rows) {
+      const key = `${row.tenant_id}:${row.tool_name}`;
+      const existing =
+        grouped.get(key) ??
+        {
+          tenant_id: row.tenant_id,
+          tool_name: row.tool_name,
+          request_count: 0,
+          error_count: 0,
+          total_units: 0,
+          latencies: [],
+          last: row.created_at
+        };
+      existing.request_count += 1;
+      existing.error_count += row.status === "error" ? 1 : 0;
+      existing.total_units += Number(row.units);
+      existing.latencies.push(Number(row.latency_ms));
+      if (row.created_at > existing.last) {
+        existing.last = row.created_at;
+      }
+      grouped.set(key, existing);
+    }
+
+    return [...grouped.values()].map((row) => ({
+      tenant_id: row.tenant_id,
+      tool_name: row.tool_name,
+      request_count: row.request_count,
+      error_count: row.error_count,
+      total_units: row.total_units,
+      p95_latency_ms: percentile(row.latencies, 0.95),
+      last_seen_at: row.last
+    }));
+  }
+
+  async listAuditEvents(input?: {
+    tenant_id?: string;
+    limit?: number;
+  }): Promise<AuditEventRecord[]> {
+    const where = input?.tenant_id ? "WHERE tenant_id = ?" : "";
+    const limit = Math.max(1, input?.limit ?? 100);
+    const rows = this.db
+      .prepare(
+        `
+        SELECT id AS event_id, tenant_id, subject, action, resource, status, trace_id, details, created_at
+        FROM audit_events
+        ${where}
+        ORDER BY created_at DESC
+        LIMIT ?
+        `
+      )
+      .all(...(input?.tenant_id ? [input.tenant_id, limit] : [limit])) as Array<{
+      event_id: string;
+      tenant_id: string;
+      subject: string;
+      action: string;
+      resource: string;
+      status: "success" | "error" | "denied";
+      trace_id: string;
+      details: string | null;
+      created_at: string;
+    }>;
+
+    return rows.map((row) => ({
+      event_id: row.event_id,
+      tenant_id: row.tenant_id,
+      subject: row.subject,
+      action: row.action,
+      resource: row.resource,
+      status: row.status,
+      trace_id: row.trace_id,
+      ...(row.details ? { details: JSON.parse(row.details) as Record<string, unknown> } : {}),
+      created_at: row.created_at
+    }));
+  }
+}
+
+export class PostgresUsageMeterStore implements UsageMeterStore {
+  constructor(private readonly pool: Pool) {}
+
+  async migrate(): Promise<void> {
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS usage_metering (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        workspace_id TEXT,
+        tool_name TEXT NOT NULL,
+        trace_id TEXT NOT NULL,
+        status TEXT NOT NULL,
+        latency_ms INTEGER NOT NULL,
+        result_count INTEGER NOT NULL,
+        units INTEGER NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    `);
+    await this.pool.query("CREATE INDEX IF NOT EXISTS idx_usage_metering_tenant_created ON usage_metering(tenant_id, created_at DESC)");
+
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS audit_events (
+        id TEXT PRIMARY KEY,
+        tenant_id TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        action TEXT NOT NULL,
+        resource TEXT NOT NULL,
+        status TEXT NOT NULL,
+        trace_id TEXT NOT NULL,
+        details JSONB,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    `);
+    await this.pool.query("CREATE INDEX IF NOT EXISTS idx_audit_events_tenant_created ON audit_events(tenant_id, created_at DESC)");
+  }
+
+  async recordUsage(input: UsageMeteringRecordInput): Promise<void> {
+    await this.pool.query(
+      `
+      INSERT INTO usage_metering
+        (id, tenant_id, workspace_id, tool_name, trace_id, status, latency_ms, result_count, units, created_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10::timestamptz)
+      `,
+      [
+        `usg_${randomUUID()}`,
+        input.tenant_id,
+        input.workspace_id ?? null,
+        input.tool_name,
+        input.trace_id,
+        input.status,
+        Math.max(0, Math.floor(input.latency_ms)),
+        Math.max(0, Math.floor(input.result_count)),
+        Math.max(0, Math.floor(input.units)),
+        input.created_at ?? nowIso()
+      ]
+    );
+  }
+
+  async recordAuditEvent(input: AuditEventInput): Promise<void> {
+    await this.pool.query(
+      `
+      INSERT INTO audit_events
+        (id, tenant_id, subject, action, resource, status, trace_id, details, created_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9::timestamptz)
+      `,
+      [
+        `aud_${randomUUID()}`,
+        input.tenant_id,
+        input.subject,
+        input.action,
+        input.resource,
+        input.status,
+        input.trace_id,
+        JSON.stringify(input.details ?? null),
+        input.created_at ?? nowIso()
+      ]
+    );
+  }
+
+  async listUsageSummary(input?: {
+    tenant_id?: string;
+    from?: string;
+    to?: string;
+  }): Promise<UsageSummary[]> {
+    const where: string[] = [];
+    const params: unknown[] = [];
+    if (input?.tenant_id) {
+      params.push(input.tenant_id);
+      where.push(`tenant_id = $${params.length}`);
+    }
+    if (input?.from) {
+      params.push(input.from);
+      where.push(`created_at >= $${params.length}::timestamptz`);
+    }
+    if (input?.to) {
+      params.push(input.to);
+      where.push(`created_at <= $${params.length}::timestamptz`);
+    }
+
+    const result = await this.pool.query<{
+      tenant_id: string;
+      tool_name: string;
+      request_count: number;
+      error_count: number;
+      total_units: number;
+      p95_latency_ms: number;
+      last_seen_at: unknown;
+    }>(
+      `
+      SELECT
+        tenant_id,
+        tool_name,
+        COUNT(*)::int AS request_count,
+        COUNT(*) FILTER (WHERE status = 'error')::int AS error_count,
+        COALESCE(SUM(units), 0)::int AS total_units,
+        COALESCE(PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY latency_ms), 0)::double precision AS p95_latency_ms,
+        MAX(created_at) AS last_seen_at
+      FROM usage_metering
+      ${where.length > 0 ? `WHERE ${where.join(" AND ")}` : ""}
+      GROUP BY tenant_id, tool_name
+      ORDER BY tenant_id, tool_name
+      `,
+      params
+    );
+
+    return result.rows.map((row) => ({
+      tenant_id: row.tenant_id,
+      tool_name: row.tool_name,
+      request_count: Number(row.request_count),
+      error_count: Number(row.error_count),
+      total_units: Number(row.total_units),
+      p95_latency_ms: Number(row.p95_latency_ms),
+      ...(row.last_seen_at ? { last_seen_at: toIsoString(row.last_seen_at) } : {})
+    }));
+  }
+
+  async listAuditEvents(input?: {
+    tenant_id?: string;
+    limit?: number;
+  }): Promise<AuditEventRecord[]> {
+    const params: unknown[] = [];
+    const where: string[] = [];
+    if (input?.tenant_id) {
+      params.push(input.tenant_id);
+      where.push(`tenant_id = $${params.length}`);
+    }
+    params.push(Math.max(1, input?.limit ?? 100));
+    const limitIndex = params.length;
+
+    const result = await this.pool.query<{
+      event_id: string;
+      tenant_id: string;
+      subject: string;
+      action: string;
+      resource: string;
+      status: "success" | "error" | "denied";
+      trace_id: string;
+      details: Record<string, unknown> | null;
+      created_at: unknown;
+    }>(
+      `
+      SELECT id AS event_id, tenant_id, subject, action, resource, status, trace_id, details, created_at
+      FROM audit_events
+      ${where.length > 0 ? `WHERE ${where.join(" AND ")}` : ""}
+      ORDER BY created_at DESC
+      LIMIT $${limitIndex}
+      `,
+      params
+    );
+
+    return result.rows.map((row) => ({
+      event_id: row.event_id,
+      tenant_id: row.tenant_id,
+      subject: row.subject,
+      action: row.action,
+      resource: row.resource,
+      status: row.status,
+      trace_id: row.trace_id,
+      ...(row.details ? { details: row.details } : {}),
+      created_at: toIsoString(row.created_at)
+    }));
+  }
+}
+
+export function createRedisClient(url: string): RedisClient {
+  return new Redis(url);
+}
+
+export function buildQueryCacheKey(input: {
+  workspace_id: string;
+  index_version: string;
+  query: string;
+  top_k: number;
+  filters?: {
+    language?: string;
+    path_prefix?: string;
+    glob?: string;
+  };
+}): string {
+  const digest = sha256(
+    JSON.stringify({
+      query: input.query,
+      top_k: input.top_k,
+      filters: input.filters ?? null,
+      index_version: input.index_version
+    })
+  );
+  return `${input.workspace_id}:${input.index_version}:${digest}`;
+}