@liendev/core 0.21.0 → 0.22.0

package/dist/vectordb/qdrant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"qdrant.d.ts","sourceRoot":"","sources":["../../src/vectordb/qdrant.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOpD;;;;;;;;GAQG;AACH,qBAAa,QAAS,YAAW,iBAAiB;IAChD,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAkB;IACrC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,gBAAgB,CAAa;IACrC,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,aAAa,CAAsB;gBAGzC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM;IA8BrB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAUrB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAMjB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgC3B,WAAW,CACf,OAAO,EAAE,YAAY,EAAE,EACvB,SAAS,EAAE,aAAa,EAAE,EAC1B,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,IAAI,CAAC;IA+CV,MAAM,CACV,WAAW,EAAE,YAAY,EACzB,KAAK,GAAE,MAAU,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,EAAE,CAAC;IAgC1B;;;OAGG;IACG,eAAe,CACnB,WAAW,EAAE,YAAY,EACzB,KAAK,GAAE,MAAU,EACjB,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC;IAwCpB,cAAc,CAAC,OAAO,EAAE;QAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA4CrB,OAAO,CAAC,OAAO,GAAE;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;KACb,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAQhC;;;OAGG;IACG,aAAa,CAAC,OAAO,EAAE;QAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAkDrB,YAAY,CAAC,OAAO,EAAE;QAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,UAAU,GAAG,OAAO,GAAG,WAAW,CAAC;QAChD,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA+CrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BtB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB7C,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,YAAY,EAAE,EACvB,SAAS,EAAE,aAAa,EAAE,EAC1B,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,IAAI,CAAC;IAyBV,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAajC;;OAEG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,SAAS,IAAI,MAAM;IAIb,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC;IAyBhC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAahC,iBAAiB,IAAI,MAAM;IAI3B,cAAc,IAAI,MAAM;CAMzB"}
+{"version":3,"file":"qdrant.d.ts","sourceRoot":"","sources":["../../src/vectordb/qdrant.ts"],"names":[],"mappings":"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"}

package/dist/vectordb/qdrant.js

@@ -7,36 +7,145 @@ import { calculateRelevance } from './relevance.js';
 import { DatabaseError } from '../errors/index.js';
 import { readVersionFile } from './version.js';
 import { QdrantPayloadMapper } from './qdrant-payload-mapper.js';
+/**
+ * Builder class for constructing Qdrant filters.
+ * Simplifies filter construction and reduces complexity.
+ */
+class QdrantFilterBuilder {
+    filter;
+    constructor(orgId) {
+        this.filter = {
+            must: [{ key: 'orgId', match: { value: orgId } }],
+        };
+    }
+    addRepoContext(repoId, branch, commitSha) {
+        this.filter.must.push({ key: 'repoId', match: { value: repoId } }, { key: 'branch', match: { value: branch } }, { key: 'commitSha', match: { value: commitSha } });
+        return this;
+    }
+    addRepoIds(repoIds) {
+        const cleanedRepoIds = repoIds
+            .map(id => id.trim())
+            .filter(id => id.length > 0);
+        // If caller passed repoIds but all were empty/invalid after cleaning,
+        // fail fast instead of silently dropping the repoId filter (which would
+        // otherwise widen the query to all repos in the org).
+        if (repoIds.length > 0 && cleanedRepoIds.length === 0) {
+            throw new Error('Invalid repoIds: all provided repoIds are empty or whitespace. ' +
+                'Provide at least one non-empty repoId or omit repoIds entirely.');
+        }
+        if (cleanedRepoIds.length > 0) {
+            this.filter.must.push({
+                key: 'repoId',
+                match: { any: cleanedRepoIds },
+            });
+        }
+        return this;
+    }
+    addLanguage(language) {
+        const cleanedLanguage = language.trim();
+        if (cleanedLanguage.length === 0) {
+            throw new Error('Invalid language: language must be a non-empty, non-whitespace string.');
+        }
+        this.filter.must.push({ key: 'language', match: { value: cleanedLanguage } });
+        return this;
+    }
+    addSymbolType(symbolType) {
+        const cleanedSymbolType = symbolType.trim();
+        if (cleanedSymbolType.length === 0) {
+            throw new Error('Invalid symbolType: symbolType must be a non-empty, non-whitespace string.');
+        }
+        this.filter.must.push({ key: 'symbolType', match: { value: cleanedSymbolType } });
+        return this;
+    }
+    addPattern(pattern, key = 'file') {
+        const cleanedPattern = pattern.trim();
+        if (cleanedPattern.length === 0) {
+            throw new Error('Invalid pattern: pattern must be a non-empty, non-whitespace string.');
+        }
+        this.filter.must.push({ key, match: { text: cleanedPattern } });
+        return this;
+    }
+    addBranch(branch) {
+        const cleanedBranch = branch.trim();
+        // Prevent constructing a filter for an empty/whitespace-only branch,
+        // which would search for `branch == ""` and almost certainly return no results.
+        if (cleanedBranch.length === 0) {
+            throw new Error('Invalid branch: branch must be a non-empty, non-whitespace string.');
+        }
+        this.filter.must.push({ key: 'branch', match: { value: cleanedBranch } });
+        return this;
+    }
+    build() {
+        return this.filter;
+    }
+}
+/**
+ * Validate filter options for buildBaseFilter.
+ *
+ * This is a separate function to enable unit testing of validation logic.
+ * The validations ensure that conflicting options are not used together.
+ *
+ * @param options - Filter options to validate
+ * @throws Error if conflicting options are detected
+ */
+export function validateFilterOptions(options) {
+    // Validate: includeCurrentRepo and repoIds are mutually exclusive
+    // Note: `includeCurrentRepo !== false` treats undefined as "enabled" (default behavior).
+    // Callers must explicitly pass includeCurrentRepo=false when using repoIds for cross-repo queries.
+    if (options.includeCurrentRepo !== false && options.repoIds && options.repoIds.length > 0) {
+        throw new Error('Cannot use repoIds when includeCurrentRepo is enabled (the default). ' +
+            'These options are mutually exclusive. Set includeCurrentRepo=false to perform cross-repo queries with repoIds.');
+    }
+    // Validate: branch parameter should only be used when includeCurrentRepo is false.
+    // As above, `includeCurrentRepo !== false` treats both undefined and true as "enabled"
+    // for the current repo context, so callers must explicitly pass false for cross-repo.
+    if (options.branch && options.includeCurrentRepo !== false) {
+        throw new Error('Cannot use branch parameter when includeCurrentRepo is enabled (the default). ' +
+            'Branch is automatically included via the current repo context. Set includeCurrentRepo=false to specify a branch explicitly.');
+    }
+}
 /**
  * QdrantDB implements VectorDBInterface using Qdrant vector database.
  *
  * Features:
  * - Multi-tenant support via payload filtering (orgId/repoId)
+ * - Branch and commit isolation for PR workflows
  * - Collection naming: `lien_org_{orgId}`
  * - Cross-repo search by omitting repoId filter
  * - Tenant isolation via orgId filtering
+ * - Point ID generation includes branch/commit to prevent collisions
+ *
+ * Data Isolation:
+ * All queries are filtered by orgId, repoId, branch, and commitSha by default.
+ * This ensures that different branches and commits have isolated data, preventing
+ * PRs from overwriting each other's indices. Use cross-repo methods (searchCrossRepo,
+ * scanCrossRepo) to query across repositories within an organization.
  */
 export class QdrantDB {
     client;
     collectionName;
     orgId;
     repoId;
+    branch;
+    commitSha;
     initialized = false;
     dbPath; // For compatibility with manifest/version file operations
     lastVersionCheck = 0;
     currentVersion = 0;
     payloadMapper;
-    constructor(url, apiKey, orgId, projectRoot) {
+    constructor(url, apiKey, orgId, projectRoot, branch, commitSha) {
         this.client = new QdrantClient({
             url,
             apiKey, // Optional, required for Qdrant Cloud
         });
         this.orgId = orgId;
         this.repoId = this.extractRepoId(projectRoot);
+        this.branch = branch;
+        this.commitSha = commitSha;
         // Collection naming: one per org
         this.collectionName = `lien_org_${orgId}`;
         // Initialize payload mapper
-        this.payloadMapper = new QdrantPayloadMapper(this.orgId, this.repoId);
+        this.payloadMapper = new QdrantPayloadMapper(this.orgId, this.repoId, this.branch, this.commitSha);
         // dbPath is used for manifest and version files (stored locally even with Qdrant)
         // Use same path structure as LanceDB for consistency
         const projectName = path.basename(projectRoot);
@@ -62,12 +171,113 @@ export class QdrantDB {
     }
     /**
      * Generate a unique point ID from chunk metadata.
-     * Uses hash of file path + line range for stable identification.
+     * Uses hash of file path + line range + branch + commitSha for stable identification.
+     * Includes branch/commit to prevent ID collisions across branches.
+     *
+     * **Hash Algorithm Choice:**
+     * Uses MD5 for performance and collision likelihood acceptable for this use case.
+     * - MD5 is deprecated for cryptographic purposes but suitable for non-security ID generation
+     * - Collision probability is extremely low: ~1 in 2^64 for random inputs
+     * - Input includes file path, line range, branch, and commit SHA, making collisions
+     *   even less likely in practice
+     * - For typical codebases (thousands to hundreds of thousands of chunks), collision risk
+     *   is negligible
+     * - If scaling to millions of chunks across many repos, consider upgrading to SHA-256
+     *   for additional collision resistance (at ~10% performance cost)
      */
     generatePointId(metadata) {
-        const idString = `${metadata.file}:${metadata.startLine}:${metadata.endLine}`;
+        const idString = `${metadata.file}:${metadata.startLine}:${metadata.endLine}:${this.branch}:${this.commitSha}`;
         return crypto.createHash('md5').update(idString).digest('hex');
     }
+    /**
+     * Build base filter for Qdrant queries.
+     * Uses builder pattern to simplify filter construction.
+     *
+     * **Important constraints:**
+     * - `includeCurrentRepo` and `repoIds` are mutually exclusive.
+     * - `includeCurrentRepo` defaults to `true` when `undefined` (treats `undefined` as "enabled").
+     * - To use `repoIds` for cross-repo queries, you must explicitly pass `includeCurrentRepo: false`.
+     * - The `branch` parameter can only be used when `includeCurrentRepo` is explicitly `false`.
+     *   When `includeCurrentRepo` is enabled (default), branch is automatically included via
+     *   the current repo context (`addRepoContext`).
+     *
+     * @param options - Filter options
+     * @param options.includeCurrentRepo - Whether to filter by current repo context (default: true when undefined).
+     *   Must be explicitly `false` to use `repoIds` or `branch` parameters.
+     * @param options.repoIds - Repository IDs to filter by (requires `includeCurrentRepo: false`).
+     * @param options.branch - Branch name to filter by (requires `includeCurrentRepo: false`).
+     * @returns Qdrant filter object
+     */
+    buildBaseFilter(options) {
+        // Validate filter options (extracted to enable unit testing)
+        validateFilterOptions({
+            repoIds: options.repoIds,
+            branch: options.branch,
+            includeCurrentRepo: options.includeCurrentRepo,
+        });
+        const builder = new QdrantFilterBuilder(this.orgId);
+        if (options.includeCurrentRepo !== false) {
+            builder.addRepoContext(this.repoId, this.branch, this.commitSha);
+        }
+        if (options.repoIds) {
+            builder.addRepoIds(options.repoIds);
+        }
+        // Validate language is non-empty if explicitly provided (even if empty string)
+        if (options.language !== undefined) {
+            builder.addLanguage(options.language);
+        }
+        // Validate symbolType is non-empty if explicitly provided (even if empty string)
+        if (options.symbolType !== undefined) {
+            builder.addSymbolType(options.symbolType);
+        }
+        // Validate pattern is non-empty if explicitly provided (even if empty string)
+        if (options.pattern !== undefined) {
+            builder.addPattern(options.pattern, options.patternKey);
+        }
+        // Only add branch filter when includeCurrentRepo is false
+        // When includeCurrentRepo is true, branch is already added via addRepoContext
+        // Validate branch is non-empty if explicitly provided (even if empty string)
+        if (options.branch !== undefined && options.includeCurrentRepo === false) {
+            // addBranch will validate that branch is non-empty and non-whitespace
+            builder.addBranch(options.branch);
+        }
+        return builder.build();
+    }
+    /**
+     * Map Qdrant scroll results to SearchResult format.
+     *
+     * Note: Scroll/scan operations do not compute semantic similarity scores.
+     * For these results, score is always 0 and relevance is set to 'not_relevant'
+     * to indicate that the results are unscored (not that they are useless).
+     */
+    mapScrollResults(results) {
+        return (results.points || []).map((point) => ({
+            content: point.payload?.content || '',
+            metadata: this.payloadMapper.fromPayload(point.payload || {}),
+            score: 0,
+            relevance: 'not_relevant',
+        }));
+    }
+    /**
+     * Execute a scroll query with error handling.
+     */
+    async executeScrollQuery(filter, limit, errorContext) {
+        if (!this.initialized) {
+            throw new DatabaseError('Qdrant database not initialized');
+        }
+        try {
+            const results = await this.client.scroll(this.collectionName, {
+                filter,
+                limit,
+                with_payload: true,
+                with_vector: false,
+            });
+            return this.mapScrollResults(results);
+        }
+        catch (error) {
+            throw new DatabaseError(`Failed to ${errorContext}: ${error instanceof Error ? error.message : String(error)}`, { collectionName: this.collectionName });
+        }
+    }
     async initialize() {
         try {
             // Check if collection exists (returns { exists: boolean })
@@ -95,7 +305,10 @@ export class QdrantDB {
             throw new DatabaseError(`Failed to initialize Qdrant database: ${error instanceof Error ? error.message : String(error)}`, { collectionName: this.collectionName });
         }
     }
-    async insertBatch(vectors, metadatas, contents) {
+    /**
+     * Validate batch input arrays have matching lengths.
+     */
+    validateBatchInputs(vectors, metadatas, contents) {
         if (!this.initialized) {
             throw new DatabaseError('Qdrant database not initialized');
         }
@@ -106,20 +319,28 @@ export class QdrantDB {
                 contentsLength: contents.length,
             });
         }
+    }
+    /**
+     * Prepare Qdrant points from vectors, metadatas, and contents.
+     */
+    preparePoints(vectors, metadatas, contents) {
+        return vectors.map((vector, i) => {
+            const metadata = metadatas[i];
+            const payload = this.payloadMapper.toPayload(metadata, contents[i]);
+            return {
+                id: this.generatePointId(metadata),
+                vector: Array.from(vector),
+                payload,
+            };
+        });
+    }
+    async insertBatch(vectors, metadatas, contents) {
+        this.validateBatchInputs(vectors, metadatas, contents);
         if (vectors.length === 0) {
             return; // No-op for empty batches
         }
         try {
-            // Prepare points for upsert
-            const points = vectors.map((vector, i) => {
-                const metadata = metadatas[i];
-                const payload = this.payloadMapper.toPayload(metadata, contents[i]);
-                return {
-                    id: this.generatePointId(metadata),
-                    vector: Array.from(vector),
-                    payload,
-                };
-            });
+            const points = this.preparePoints(vectors, metadatas, contents);
             // Upsert points in batches (Qdrant recommends batches of 100-1000)
             const batchSize = 100;
             for (let i = 0; i < points.length; i += batchSize) {
@@ -140,7 +361,7 @@ export class QdrantDB {
             throw new DatabaseError('Qdrant database not initialized');
         }
         try {
-            // Search with tenant isolation (filter by orgId and repoId)
+            // Search with tenant isolation (filter by orgId, repoId, branch, and commitSha)
             const results = await this.client.search(this.collectionName, {
                 vector: Array.from(queryVector),
                 limit,
@@ -148,6 +369,8 @@ export class QdrantDB {
                     must: [
                         { key: 'orgId', match: { value: this.orgId } },
                         { key: 'repoId', match: { value: this.repoId } },
+                        { key: 'branch', match: { value: this.branch } },
+                        { key: 'commitSha', match: { value: this.commitSha } },
                     ],
                 },
             });
@@ -164,25 +387,35 @@ export class QdrantDB {
     }
     /**
      * Search across all repos in the organization (cross-repo search).
-     * Omits repoId filter to enable cross-repo queries.
+     *
+     * - Omits repoId filter by default to enable true cross-repo queries.
+     * - When repoIds are provided, restricts results to those repositories only.
+     * - When branch is omitted, returns chunks from all branches and commits
+     *   (including historical PR branches and stale commits).
+     * - When branch is provided, filters by branch name only and still returns
+     *   chunks from all commits on that branch across the selected repos.
+     *
+     * This is a low-level primitive for cross-repo augmentation. Higher-level
+     * workflows (e.g. \"latest commit only\") should be built on top of this API.
+     *
+     * @param queryVector - Query vector for semantic search
+     * @param limit - Maximum number of results to return (default: 5)
+     * @param options - Optional search options
+     * @param options.repoIds - Repository IDs to filter by (optional)
+     * @param options.branch - Branch name to filter by (optional)
      */
-    async searchCrossRepo(queryVector, limit = 5, repoIds) {
+    async searchCrossRepo(queryVector, limit = 5, options) {
         if (!this.initialized) {
             throw new DatabaseError('Qdrant database not initialized');
         }
         try {
-            const filter = {
-                must: [
-                    { key: 'orgId', match: { value: this.orgId } },
-                ],
-            };
-            // Optionally filter to specific repos
-            if (repoIds && repoIds.length > 0) {
-                filter.must.push({
-                    key: 'repoId',
-                    match: { any: repoIds },
-                });
-            }
+            // Use buildBaseFilter for consistency with scanCrossRepo and other methods
+            // This provides automatic validation for empty repoIds arrays, whitespace-only branches, etc.
+            const filter = this.buildBaseFilter({
+                includeCurrentRepo: false,
+                repoIds: options?.repoIds,
+                branch: options?.branch,
+            });
             const results = await this.client.search(this.collectionName, {
                 vector: Array.from(queryVector),
                 limit,
@@ -200,40 +433,13 @@ export class QdrantDB {
         }
     }
     async scanWithFilter(options) {
-        if (!this.initialized) {
-            throw new DatabaseError('Qdrant database not initialized');
-        }
-        try {
-            const filter = {
-                must: [
-                    { key: 'orgId', match: { value: this.orgId } },
-                    { key: 'repoId', match: { value: this.repoId } },
-                ],
-            };
-            if (options.language) {
-                filter.must.push({ key: 'language', match: { value: options.language } });
-            }
-            if (options.pattern) {
-                // Qdrant supports regex in match filters
-                filter.must.push({ key: 'file', match: { text: options.pattern } });
-            }
-            const limit = options.limit || 100;
-            const results = await this.client.scroll(this.collectionName, {
-                filter,
-                limit,
-                with_payload: true,
-                with_vector: false,
-            });
-            return (results.points || []).map(point => ({
-                content: point.payload?.content || '',
-                metadata: this.payloadMapper.fromPayload(point.payload || {}),
-                score: 0, // No relevance score for filtered scans
-                relevance: 'not_relevant',
-            }));
-        }
-        catch (error) {
-            throw new DatabaseError(`Failed to scan Qdrant: ${error instanceof Error ? error.message : String(error)}`, { collectionName: this.collectionName });
-        }
+        const filter = this.buildBaseFilter({
+            language: options.language,
+            pattern: options.pattern,
+            patternKey: 'file',
+            includeCurrentRepo: true,
+        });
+        return this.executeScrollQuery(filter, options.limit || 100, 'scan Qdrant');
     }
     async scanAll(options = {}) {
         // Use scanWithFilter with a high limit to get all chunks
@@ -244,111 +450,100 @@ export class QdrantDB {
     }
     /**
      * Scan with filter across all repos in the organization (cross-repo).
-     * Omits repoId filter to enable cross-repo queries.
+     *
+     * - Omits repoId filter by default to enable true cross-repo scans.
+     * - When repoIds are provided, restricts results to those repositories only.
+     * - When branch is omitted, returns chunks from all branches and commits
+     *   (including historical PR branches and stale commits).
+     * - When branch is provided, filters by branch name only and still returns
+     *   chunks from all commits on that branch across the selected repos.
+     *
+     * Like searchCrossRepo, this is a low-level primitive. Higher-level behavior
+     * such as \"latest commit only\" should be implemented in orchestrating code.
      */
     async scanCrossRepo(options) {
-        if (!this.initialized) {
-            throw new DatabaseError('Qdrant database not initialized');
-        }
-        try {
-            const filter = {
-                must: [
-                    { key: 'orgId', match: { value: this.orgId } },
-                ],
-            };
-            // Optionally filter to specific repos
-            if (options.repoIds && options.repoIds.length > 0) {
-                filter.must.push({
-                    key: 'repoId',
-                    match: { any: options.repoIds },
-                });
-            }
-            if (options.language) {
-                filter.must.push({ key: 'language', match: { value: options.language } });
-            }
-            if (options.pattern) {
-                filter.must.push({ key: 'file', match: { text: options.pattern } });
-            }
-            const limit = options.limit || 10000; // Higher default for cross-repo
-            const results = await this.client.scroll(this.collectionName, {
-                filter,
-                limit,
-                with_payload: true,
-                with_vector: false,
-            });
-            return (results.points || []).map(point => ({
-                content: point.payload?.content || '',
-                metadata: this.payloadMapper.fromPayload(point.payload || {}),
-                score: 0,
-                relevance: 'not_relevant',
-            }));
-        }
-        catch (error) {
-            throw new DatabaseError(`Failed to scan Qdrant (cross-repo): ${error instanceof Error ? error.message : String(error)}`, { collectionName: this.collectionName });
-        }
+        const filter = this.buildBaseFilter({
+            language: options.language,
+            pattern: options.pattern,
+            patternKey: 'file',
+            repoIds: options.repoIds,
+            branch: options.branch,
+            includeCurrentRepo: false, // Cross-repo: don't filter by current repo
+        });
+        return this.executeScrollQuery(filter, options.limit || 10000, // Higher default for cross-repo
+        'scan Qdrant (cross-repo)');
     }
     async querySymbols(options) {
+        const filter = this.buildBaseFilter({
+            language: options.language,
+            pattern: options.pattern,
+            patternKey: 'symbolName',
+            symbolType: options.symbolType,
+            includeCurrentRepo: true,
+        });
+        return this.executeScrollQuery(filter, options.limit || 100, 'query symbols in Qdrant');
+    }
+    async clear() {
         if (!this.initialized) {
             throw new DatabaseError('Qdrant database not initialized');
         }
         try {
-            const filter = {
-                must: [
-                    { key: 'orgId', match: { value: this.orgId } },
-                    { key: 'repoId', match: { value: this.repoId } },
-                ],
-            };
-            if (options.language) {
-                filter.must.push({ key: 'language', match: { value: options.language } });
-            }
-            if (options.symbolType) {
-                filter.must.push({ key: 'symbolType', match: { value: options.symbolType } });
-            }
-            if (options.pattern) {
-                filter.must.push({ key: 'symbolName', match: { text: options.pattern } });
+            // Check if collection exists before trying to clear it (returns { exists: boolean })
+            const collectionCheck = await this.client.collectionExists(this.collectionName);
+            if (!collectionCheck.exists) {
+                // Collection doesn't exist yet, nothing to clear
+                return;
             }
-            const limit = options.limit || 100;
-            const results = await this.client.scroll(this.collectionName, {
-                filter,
-                limit,
-                with_payload: true,
-                with_vector: false,
+            // Delete all points for this repository and branch/commit only
+            // This ensures we only clear the current branch's data, not all branches
+            await this.client.delete(this.collectionName, {
+                filter: {
+                    must: [
+                        { key: 'orgId', match: { value: this.orgId } },
+                        { key: 'repoId', match: { value: this.repoId } },
+                        { key: 'branch', match: { value: this.branch } },
+                        { key: 'commitSha', match: { value: this.commitSha } },
+                    ],
+                },
             });
-            return (results.points || []).map(point => ({
-                content: point.payload?.content || '',
-                metadata: this.payloadMapper.fromPayload(point.payload || {}),
-                score: 0,
-                relevance: 'not_relevant',
-            }));
         }
         catch (error) {
-            throw new DatabaseError(`Failed to query symbols in Qdrant: ${error instanceof Error ? error.message : String(error)}`, { collectionName: this.collectionName });
+            throw new DatabaseError(`Failed to clear Qdrant collection: ${error instanceof Error ? error.message : String(error)}`, { collectionName: this.collectionName });
         }
     }
-    async clear() {
+    /**
+     * Clear all data for a specific branch (all commits).
+     *
+     * Qdrant-only helper: this is not part of the generic VectorDBInterface and
+     * is intended for cloud/PR workflows where multiple commits exist per branch.
+     * LanceDB and other backends do not implement this method.
+     *
+     * @param branch - Branch name to clear (defaults to current branch)
+     */
+    async clearBranch(branch) {
         if (!this.initialized) {
             throw new DatabaseError('Qdrant database not initialized');
         }
+        const targetBranch = branch ?? this.branch;
         try {
-            // Check if collection exists before trying to clear it (returns { exists: boolean })
             const collectionCheck = await this.client.collectionExists(this.collectionName);
             if (!collectionCheck.exists) {
                 // Collection doesn't exist yet, nothing to clear
                 return;
             }
-            // Delete all points for this repository only (filter by both orgId and repoId)
-            // This ensures we only clear the current repo's data, not all repos in the org
+            // Delete all points for this repository and branch (all commits)
             await this.client.delete(this.collectionName, {
                 filter: {
                     must: [
                         { key: 'orgId', match: { value: this.orgId } },
                         { key: 'repoId', match: { value: this.repoId } },
+                        { key: 'branch', match: { value: targetBranch } },
                     ],
                 },
             });
         }
         catch (error) {
-            throw new DatabaseError(`Failed to clear Qdrant collection: ${error instanceof Error ? error.message : String(error)}`, { collectionName: this.collectionName });
+            throw new DatabaseError(`Failed to clear branch from Qdrant: ${error instanceof Error ? error.message : String(error)}`, { collectionName: this.collectionName, branch: targetBranch });
         }
     }
     async deleteByFile(filepath) {
@@ -361,6 +556,8 @@ export class QdrantDB {
                     must: [
                         { key: 'orgId', match: { value: this.orgId } },
                         { key: 'repoId', match: { value: this.repoId } },
+                        { key: 'branch', match: { value: this.branch } },
+                        { key: 'commitSha', match: { value: this.commitSha } },
                         { key: 'file', match: { value: filepath } },
                     ],
                 },