@zokizuan/satori-core 1.2.0 → 1.5.0

package/README.md

@@ -36,7 +36,13 @@ const context = new Context({
 });
 
 await context.indexCodebase('/absolute/path/to/repo');
-const results = await context.semanticSearch('/absolute/path/to/repo', 'authentication logic', 5);
+const results = await context.semanticSearch({
+  codebasePath: '/absolute/path/to/repo',
+  query: 'authentication logic',
+  topK: 5,
+  retrievalMode: 'hybrid',
+  scorePolicy: { kind: 'topk_only' }
+});
 ```
 
 ## Development

package/dist/core/context.d.ts

@@ -1,7 +1,7 @@
 import { Splitter } from '../splitter';
 import { Embedding } from '../embedding';
 import { VectorDatabase, IndexCompletionMarkerDocument } from '../vectordb';
-import { SemanticSearchResult } from '../types';
+import { SemanticSearchRequest, SemanticSearchResult } from '../types';
 import { FileSynchronizer } from '../sync/synchronizer';
 export interface ContextConfig {
     embedding?: Embedding;
@@ -125,7 +125,10 @@ export declare class Context {
      * @param topK Number of results to return
      * @param threshold Similarity threshold
      */
+    semanticSearch(request: SemanticSearchRequest): Promise<SemanticSearchResult[]>;
     semanticSearch(codebasePath: string, query: string, topK?: number, threshold?: number, filterExpr?: string): Promise<SemanticSearchResult[]>;
+    private normalizeSemanticSearchRequest;
+    private resolveSemanticSearchRequest;
     private buildSemanticSearchFilterExpr;
     private queryCompletionMarkerRows;
     clearIndexCompletionMarker(codebasePath: string): Promise<void>;

package/dist/core/context.js

@@ -353,18 +353,14 @@ class Context {
             }
         }
     }
-    /**
-     * Semantic search with unified implementation
-     * @param codebasePath Codebase path to search in
-     * @param query Search query
-     * @param topK Number of results to return
-     * @param threshold Similarity threshold
-     */
-    async semanticSearch(codebasePath, query, topK = 5, threshold = 0.5, filterExpr) {
-        const isHybrid = this.getIsHybrid();
+    async semanticSearch(requestOrCodebasePath, query, topK = 5, threshold = 0.5, filterExpr) {
+        const request = this.normalizeSemanticSearchRequest(requestOrCodebasePath, query, topK, threshold, filterExpr);
+        const resolvedRequest = this.resolveSemanticSearchRequest(request);
+        const codebasePath = resolvedRequest.codebasePath;
+        const isHybrid = resolvedRequest.retrievalMode !== 'dense' && this.getIsHybrid() === true;
         const searchType = isHybrid === true ? 'hybrid search' : 'semantic search';
-        console.log(`[Context] 🔍 Executing ${searchType}: "${query}" in ${codebasePath}`);
-        const effectiveFilterExpr = this.buildSemanticSearchFilterExpr(filterExpr);
+        console.log(`[Context] 🔍 Executing ${searchType}: "${resolvedRequest.query}" in ${codebasePath}`);
+        const effectiveFilterExpr = this.buildSemanticSearchFilterExpr(resolvedRequest.filterExpr);
         const normalizeBreadcrumbs = (value) => {
             if (!Array.isArray(value)) {
                 return undefined;
@@ -387,15 +383,15 @@ class Context {
         if (isHybrid === true) {
             try {
                 // Check collection stats to see if it has data
-                const stats = await this.vectorDatabase.query(collectionName, '', ['id'], 1);
+                await this.vectorDatabase.query(collectionName, '', ['id'], 1);
                 console.log(`[Context] 🔍 Collection '${collectionName}' exists and appears to have data`);
             }
             catch (error) {
                 console.log(`[Context] ⚠️  Collection '${collectionName}' exists but may be empty or not properly indexed:`, error);
             }
             // 1. Generate query vector
-            console.log(`[Context] 🔍 Generating embeddings for query: "${query}"`);
-            const queryEmbedding = await this.embedding.embed(query);
+            console.log(`[Context] 🔍 Generating embeddings for query: "${resolvedRequest.query}"`);
+            const queryEmbedding = await this.embedding.embed(resolvedRequest.query);
             console.log(`[Context] ✅ Generated embedding vector with dimension: ${queryEmbedding.vector.length}`);
             console.log(`[Context] 🔍 First 5 embedding values: [${queryEmbedding.vector.slice(0, 5).join(', ')}]`);
             // 2. Prepare hybrid search requests
@@ -404,17 +400,17 @@ class Context {
                     data: queryEmbedding.vector,
                     anns_field: "vector",
                     param: { "nprobe": 10 },
-                    limit: topK
+                    limit: resolvedRequest.topK
                 },
                 {
-                    data: query,
+                    data: resolvedRequest.query,
                     anns_field: "sparse_vector",
                     param: { "drop_ratio_search": 0.2 },
-                    limit: topK
+                    limit: resolvedRequest.topK
                 }
             ];
             console.log(`[Context] 🔍 Search request 1 (dense): anns_field="${searchRequests[0].anns_field}", vector_dim=${queryEmbedding.vector.length}, limit=${searchRequests[0].limit}`);
-            console.log(`[Context] 🔍 Search request 2 (sparse): anns_field="${searchRequests[1].anns_field}", query_text="${query}", limit=${searchRequests[1].limit}`);
+            console.log(`[Context] 🔍 Search request 2 (sparse): anns_field="${searchRequests[1].anns_field}", query_text="${resolvedRequest.query}", limit=${searchRequests[1].limit}`);
             // 3. Execute hybrid search
             console.log(`[Context] 🔍 Executing hybrid search with RRF reranking...`);
             const searchResults = await this.vectorDatabase.hybridSearch(collectionName, searchRequests, {
@@ -422,7 +418,7 @@ class Context {
                     strategy: 'rrf',
                     params: { k: 100 }
                 },
-                limit: topK,
+                limit: resolvedRequest.topK,
                 // Hybrid RRF scores are backend/rerank relative, so dense similarity
                 // thresholds can erase valid sparse lexical matches before MCP ranking.
                 filterExpr: effectiveFilterExpr
@@ -439,7 +435,9 @@ class Context {
                 breadcrumbs: normalizeBreadcrumbs(result.document.metadata.breadcrumbs),
                 indexedAt: typeof result.document.metadata.indexedAt === 'string' ? result.document.metadata.indexedAt : undefined,
                 symbolId: typeof result.document.metadata.symbolId === 'string' ? result.document.metadata.symbolId : undefined,
-                symbolLabel: typeof result.document.metadata.symbolLabel === 'string' ? result.document.metadata.symbolLabel : undefined
+                symbolLabel: typeof result.document.metadata.symbolLabel === 'string' ? result.document.metadata.symbolLabel : undefined,
+                backendScore: result.score,
+                backendScoreKind: 'rrf_fusion'
             }));
             console.log(`[Context] ✅ Found ${results.length} relevant hybrid results`);
             if (results.length > 0) {
@@ -450,9 +448,12 @@ class Context {
         else {
             // Regular semantic search
             // 1. Generate query vector
-            const queryEmbedding = await this.embedding.embed(query);
+            const queryEmbedding = await this.embedding.embed(resolvedRequest.query);
+            const denseThreshold = resolvedRequest.scorePolicy.kind === 'dense_similarity_min'
+                ? resolvedRequest.scorePolicy.min
+                : undefined;
             // 2. Search in vector database
-            const searchResults = await this.vectorDatabase.search(collectionName, queryEmbedding.vector, { topK, threshold, filterExpr: effectiveFilterExpr });
+            const searchResults = await this.vectorDatabase.search(collectionName, queryEmbedding.vector, { topK: resolvedRequest.topK, threshold: denseThreshold, filterExpr: effectiveFilterExpr });
             // 3. Convert to semantic search result format
             const results = searchResults.map(result => ({
                 content: result.document.content,
@@ -464,12 +465,54 @@ class Context {
                 breadcrumbs: normalizeBreadcrumbs(result.document.metadata.breadcrumbs),
                 indexedAt: typeof result.document.metadata.indexedAt === 'string' ? result.document.metadata.indexedAt : undefined,
                 symbolId: typeof result.document.metadata.symbolId === 'string' ? result.document.metadata.symbolId : undefined,
-                symbolLabel: typeof result.document.metadata.symbolLabel === 'string' ? result.document.metadata.symbolLabel : undefined
+                symbolLabel: typeof result.document.metadata.symbolLabel === 'string' ? result.document.metadata.symbolLabel : undefined,
+                backendScore: result.score,
+                backendScoreKind: 'dense_similarity'
             }));
             console.log(`[Context] ✅ Found ${results.length} relevant results`);
             return results;
         }
     }
+    normalizeSemanticSearchRequest(requestOrCodebasePath, query, topK = 5, threshold = 0.5, filterExpr) {
+        if (typeof requestOrCodebasePath === 'string') {
+            return {
+                codebasePath: requestOrCodebasePath,
+                query: query ?? '',
+                topK,
+                filterExpr,
+                ...(threshold > 0
+                    ? {
+                        retrievalMode: 'dense',
+                        scorePolicy: { kind: 'dense_similarity_min', min: threshold }
+                    }
+                    : {
+                        scorePolicy: { kind: 'topk_only' }
+                    })
+            };
+        }
+        return requestOrCodebasePath;
+    }
+    resolveSemanticSearchRequest(request) {
+        const hybridEnabled = this.getIsHybrid() === true;
+        const retrievalMode = request.retrievalMode ?? (hybridEnabled ? 'hybrid' : 'dense');
+        const scorePolicy = request.scorePolicy ?? (retrievalMode === 'dense'
+            ? { kind: 'dense_similarity_min', min: 0.5 }
+            : { kind: 'topk_only' });
+        if (request.retrievalMode !== undefined && retrievalMode !== 'dense' && hybridEnabled !== true) {
+            throw new Error(`${retrievalMode} retrieval requires hybrid search support, but HYBRID_MODE is disabled.`);
+        }
+        if (retrievalMode !== 'dense' && scorePolicy.kind === 'dense_similarity_min') {
+            throw new Error(`Dense similarity threshold score policy is invalid for ${retrievalMode} retrieval.`);
+        }
+        return {
+            codebasePath: request.codebasePath,
+            query: request.query,
+            topK: request.topK ?? 5,
+            retrievalMode,
+            filterExpr: request.filterExpr ?? '',
+            scorePolicy
+        };
+    }
     buildSemanticSearchFilterExpr(filterExpr) {
         const markerExclusion = `fileExtension != "${vectordb_1.INDEX_COMPLETION_MARKER_FILE_EXTENSION}"`;
         if (!filterExpr || filterExpr.trim().length === 0) {
@@ -588,7 +631,7 @@ class Context {
         const collectionExists = await this.vectorDatabase.hasCollection(collectionName);
         progressCallback?.({ phase: 'Removing index data...', current: 50, total: 100, percentage: 50 });
         if (collectionExists) {
-            await this.vectorDatabase.dropCollection(collectionName);
+            await (0, vectordb_1.deleteCollectionWithVerification)(this.vectorDatabase, collectionName);
         }
         // Delete snapshot file
         await synchronizer_1.FileSynchronizer.deleteSnapshot(codebasePath);
@@ -948,7 +991,10 @@ class Context {
                 }
                 const relativePath = path.relative(codebasePath, chunk.metadata.filePath);
                 const fileExtension = path.extname(chunk.metadata.filePath);
-                const { filePath, startLine, endLine, ...restMetadata } = chunk.metadata;
+                const { filePath: omittedFilePath, startLine: omittedStartLine, endLine: omittedEndLine, ...restMetadata } = chunk.metadata;
+                void omittedFilePath;
+                void omittedStartLine;
+                void omittedEndLine;
                 return {
                     id: this.generateId(relativePath, chunk.metadata.startLine || 0, chunk.metadata.endLine || 0, chunk.content),
                     content: chunk.content, // Full text content for BM25 and storage
@@ -977,7 +1023,10 @@ class Context {
                 }
                 const relativePath = path.relative(codebasePath, chunk.metadata.filePath);
                 const fileExtension = path.extname(chunk.metadata.filePath);
-                const { filePath, startLine, endLine, ...restMetadata } = chunk.metadata;
+                const { filePath: omittedFilePath, startLine: omittedStartLine, endLine: omittedEndLine, ...restMetadata } = chunk.metadata;
+                void omittedFilePath;
+                void omittedStartLine;
+                void omittedEndLine;
                 return {
                     id: this.generateId(relativePath, chunk.metadata.startLine || 0, chunk.metadata.endLine || 0, chunk.content),
                     vector: embeddings[index].vector,
@@ -1114,7 +1163,7 @@ class Context {
                 return [];
             }
         }
-        catch (error) {
+        catch {
             if (fileName.includes('global')) {
                 console.log(`📄 No ${fileName} file found`);
             }

package/dist/splitter/ast-splitter.js

@@ -156,7 +156,7 @@ class AstCodeSplitter {
         }
         return this.addOverlap(refinedChunks);
     }
-    splitLargeChunk(chunk, originalCode) {
+    splitLargeChunk(chunk, _originalCode) {
         const lines = chunk.content.split('\n');
         const subChunks = [];
         let currentChunk = '';

package/dist/splitter/langchain-splitter.js

@@ -23,7 +23,7 @@ class LangChainCodeSplitter {
                 // Split code
                 const documents = await splitter.createDocuments([code]);
                 // Convert to CodeChunk format
-                return documents.map((doc, index) => {
+                return documents.map((doc) => {
                     const lines = doc.metadata?.loc?.lines || { from: 1, to: 1 };
                     return {
                         content: doc.pageContent,
@@ -86,7 +86,7 @@ class LangChainCodeSplitter {
             chunkOverlap: this.chunkOverlap,
         });
         const documents = await splitter.createDocuments([code]);
-        return documents.map((doc, index) => {
+        return documents.map((doc) => {
             const lines = this.estimateLines(doc.pageContent, code);
             return {
                 content: doc.pageContent,
@@ -101,7 +101,6 @@ class LangChainCodeSplitter {
     }
     estimateLines(chunk, originalCode) {
         // Simple line number estimation
-        const codeLines = originalCode.split('\n');
         const chunkLines = chunk.split('\n');
         // Find chunk position in original code
         const chunkStart = originalCode.indexOf(chunk);

package/dist/types.d.ts

@@ -1,8 +1,17 @@
+import type { BackendScoreKind, RetrievalMode, ScorePolicy } from './vectordb/types';
 export interface SearchQuery {
     term: string;
     includeContent?: boolean;
     limit?: number;
 }
+export interface SemanticSearchRequest {
+    codebasePath: string;
+    query: string;
+    topK?: number;
+    retrievalMode?: RetrievalMode;
+    filterExpr?: string;
+    scorePolicy?: ScorePolicy;
+}
 export interface SemanticSearchResult {
     content: string;
     relativePath: string;
@@ -14,5 +23,7 @@ export interface SemanticSearchResult {
     indexedAt?: string;
     symbolId?: string;
     symbolLabel?: string;
+    backendScore?: number;
+    backendScoreKind?: BackendScoreKind;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/utils/env-manager.js

@@ -64,7 +64,7 @@ class EnvManager {
                 }
             }
         }
-        catch (error) {
+        catch {
             // Ignore file read errors
         }
         return undefined;

package/dist/vectordb/index.d.ts

@@ -1,5 +1,6 @@
-export { VectorDocument, SearchOptions, VectorSearchResult, VectorDatabase, CollectionDetails, VectorStoreBackendInfo, HybridSearchRequest, HybridSearchOptions, HybridSearchResult, RerankStrategy, IndexCompletionFingerprint, IndexCompletionMarkerDocument, INDEX_COMPLETION_MARKER_DOC_ID, INDEX_COMPLETION_MARKER_FILE_EXTENSION, INDEX_COMPLETION_MARKER_RELATIVE_PATH, COLLECTION_LIMIT_MESSAGE } from './types';
+export { VectorDocument, SearchOptions, VectorSearchResult, VectorDatabase, CollectionDetails, VectorStoreBackendInfo, HybridSearchRequest, HybridSearchOptions, HybridSearchResult, RerankStrategy, RetrievalMode, ScorePolicy, BackendScoreKind, IndexCompletionFingerprint, IndexCompletionMarkerDocument, INDEX_COMPLETION_MARKER_DOC_ID, INDEX_COMPLETION_MARKER_FILE_EXTENSION, INDEX_COMPLETION_MARKER_RELATIVE_PATH, COLLECTION_LIMIT_MESSAGE } from './types';
 export { MilvusRestfulVectorDatabase, MilvusRestfulConfig } from './milvus-restful-vectordb';
 export { MilvusVectorDatabase, MilvusConfig } from './milvus-vectordb';
+export { RemoteCollectionDeletePendingError, deleteCollectionWithVerification, VerifiedCollectionDeleteOptions, VerifiedCollectionDeleteResult } from './remote-delete';
 export { ClusterManager, ZillizConfig, Project, Cluster, CreateFreeClusterRequest, CreateFreeClusterResponse, CreateFreeClusterWithDetailsResponse, DescribeClusterResponse } from './zilliz-utils';
 //# sourceMappingURL=index.d.ts.map

package/dist/vectordb/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClusterManager = exports.MilvusVectorDatabase = exports.MilvusRestfulVectorDatabase = exports.COLLECTION_LIMIT_MESSAGE = exports.INDEX_COMPLETION_MARKER_RELATIVE_PATH = exports.INDEX_COMPLETION_MARKER_FILE_EXTENSION = exports.INDEX_COMPLETION_MARKER_DOC_ID = void 0;
+exports.ClusterManager = exports.deleteCollectionWithVerification = exports.RemoteCollectionDeletePendingError = exports.MilvusVectorDatabase = exports.MilvusRestfulVectorDatabase = exports.COLLECTION_LIMIT_MESSAGE = exports.INDEX_COMPLETION_MARKER_RELATIVE_PATH = exports.INDEX_COMPLETION_MARKER_FILE_EXTENSION = exports.INDEX_COMPLETION_MARKER_DOC_ID = void 0;
 // Re-export types and interfaces
 var types_1 = require("./types");
 Object.defineProperty(exports, "INDEX_COMPLETION_MARKER_DOC_ID", { enumerable: true, get: function () { return types_1.INDEX_COMPLETION_MARKER_DOC_ID; } });
@@ -12,6 +12,9 @@ var milvus_restful_vectordb_1 = require("./milvus-restful-vectordb");
 Object.defineProperty(exports, "MilvusRestfulVectorDatabase", { enumerable: true, get: function () { return milvus_restful_vectordb_1.MilvusRestfulVectorDatabase; } });
 var milvus_vectordb_1 = require("./milvus-vectordb");
 Object.defineProperty(exports, "MilvusVectorDatabase", { enumerable: true, get: function () { return milvus_vectordb_1.MilvusVectorDatabase; } });
+var remote_delete_1 = require("./remote-delete");
+Object.defineProperty(exports, "RemoteCollectionDeletePendingError", { enumerable: true, get: function () { return remote_delete_1.RemoteCollectionDeletePendingError; } });
+Object.defineProperty(exports, "deleteCollectionWithVerification", { enumerable: true, get: function () { return remote_delete_1.deleteCollectionWithVerification; } });
 var zilliz_utils_1 = require("./zilliz-utils");
 Object.defineProperty(exports, "ClusterManager", { enumerable: true, get: function () { return zilliz_utils_1.ClusterManager; } });
 //# sourceMappingURL=index.js.map

package/dist/vectordb/milvus-restful-vectordb.d.ts

@@ -47,7 +47,7 @@ export declare class MilvusRestfulVectorDatabase implements VectorDatabase {
      * Make HTTP request to Milvus REST API
      */
     private makeRequest;
-    createCollection(collectionName: string, dimension: number, description?: string): Promise<void>;
+    createCollection(collectionName: string, dimension: number, _description?: string): Promise<void>;
     /**
      * Create index for vector field using the Index Create API
      */
@@ -65,7 +65,7 @@ export declare class MilvusRestfulVectorDatabase implements VectorDatabase {
     search(collectionName: string, queryVector: number[], options?: SearchOptions): Promise<VectorSearchResult[]>;
     delete(collectionName: string, ids: string[]): Promise<void>;
     query(collectionName: string, filter: string, outputFields: string[], limit?: number): Promise<Record<string, any>[]>;
-    createHybridCollection(collectionName: string, dimension: number, description?: string): Promise<void>;
+    createHybridCollection(collectionName: string, dimension: number, _description?: string): Promise<void>;
     private createHybridIndexes;
     insertHybrid(collectionName: string, documents: VectorDocument[]): Promise<void>;
     hybridSearch(collectionName: string, searchRequests: HybridSearchRequest[], options?: HybridSearchOptions): Promise<HybridSearchResult[]>;

package/dist/vectordb/milvus-restful-vectordb.js

@@ -13,6 +13,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MilvusRestfulVectorDatabase = void 0;
 const types_1 = require("./types");
 const zilliz_utils_1 = require("./zilliz-utils");
+const remote_delete_1 = require("./remote-delete");
 function normalizeHost(address) {
     const withProtocol = address.includes('://') ? address : `http://${address}`;
     try {
@@ -161,7 +162,7 @@ class MilvusRestfulVectorDatabase {
             throw error;
         }
     }
-    async createCollection(collectionName, dimension, description) {
+    async createCollection(collectionName, dimension, _description) {
         await this.ensureInitialized();
         try {
             const restfulConfig = this.config;
@@ -495,7 +496,7 @@ class MilvusRestfulVectorDatabase {
             throw error;
         }
     }
-    async createHybridCollection(collectionName, dimension, description) {
+    async createHybridCollection(collectionName, dimension, _description) {
         try {
             const restfulConfig = this.config;
             const collectionSchema = {
@@ -772,7 +773,7 @@ class MilvusRestfulVectorDatabase {
         };
         try {
             await createCollectionWithLimitCheck(this.makeRequest.bind(this), collectionSchema);
-            await this.dropCollection(collectionName);
+            await (0, remote_delete_1.deleteCollectionWithVerification)(this, collectionName);
             return true;
         }
         catch (error) {

package/dist/vectordb/milvus-vectordb.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MilvusVectorDatabase = void 0;
 const milvus2_sdk_node_1 = require("@zilliz/milvus2-sdk-node");
 const zilliz_utils_1 = require("./zilliz-utils");
+const remote_delete_1 = require("./remote-delete");
 const COLLECTION_LIMIT_PATTERNS = [
     /exceeded the limit number of collections/i,
     /collection limit/i,
@@ -753,12 +754,7 @@ class MilvusVectorDatabase {
         };
         try {
             await this.client.createCollection(createCollectionParams);
-            // Immediately drop the collection after successful creation
-            if (await this.client.hasCollection({ collection_name: collectionName })) {
-                await this.client.dropCollection({
-                    collection_name: collectionName,
-                });
-            }
+            await (0, remote_delete_1.deleteCollectionWithVerification)(this, collectionName);
             return true;
         }
         catch (error) {

package/dist/vectordb/remote-delete.d.ts

@@ -0,0 +1,20 @@
+import type { VectorDatabase } from './types';
+export interface VerifiedCollectionDeleteOptions {
+    maxAttempts?: number;
+    initialBackoffMs?: number;
+    backoffMultiplier?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface VerifiedCollectionDeleteResult {
+    collectionName: string;
+    attempts: number;
+    verifiedAbsent: boolean;
+}
+export declare class RemoteCollectionDeletePendingError extends Error {
+    readonly collectionName: string;
+    readonly attempts: number;
+    readonly lastError?: unknown;
+    constructor(collectionName: string, attempts: number, lastError?: unknown);
+}
+export declare function deleteCollectionWithVerification(vectorDatabase: Pick<VectorDatabase, 'dropCollection' | 'hasCollection'>, collectionName: string, options?: VerifiedCollectionDeleteOptions): Promise<VerifiedCollectionDeleteResult>;
+//# sourceMappingURL=remote-delete.d.ts.map

package/dist/vectordb/remote-delete.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteCollectionDeletePendingError = void 0;
+exports.deleteCollectionWithVerification = deleteCollectionWithVerification;
+const DEFAULT_MAX_ATTEMPTS = 5;
+const DEFAULT_INITIAL_BACKOFF_MS = 100;
+const DEFAULT_BACKOFF_MULTIPLIER = 2;
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+class RemoteCollectionDeletePendingError extends Error {
+    constructor(collectionName, attempts, lastError) {
+        const detail = lastError ? ` Last error: ${formatError(lastError)}` : '';
+        super(`Remote collection deletion did not complete for '${collectionName}' after ${attempts} attempt(s).${detail}`);
+        this.name = 'RemoteCollectionDeletePendingError';
+        this.collectionName = collectionName;
+        this.attempts = attempts;
+        this.lastError = lastError;
+    }
+}
+exports.RemoteCollectionDeletePendingError = RemoteCollectionDeletePendingError;
+async function deleteCollectionWithVerification(vectorDatabase, collectionName, options = {}) {
+    const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS));
+    const initialBackoffMs = Math.max(0, options.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS);
+    const backoffMultiplier = Math.max(1, options.backoffMultiplier ?? DEFAULT_BACKOFF_MULTIPLIER);
+    const sleep = options.sleep ?? defaultSleep;
+    if (!await vectorDatabase.hasCollection(collectionName)) {
+        return { collectionName, attempts: 0, verifiedAbsent: true };
+    }
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        lastError = undefined;
+        try {
+            await vectorDatabase.dropCollection(collectionName);
+        }
+        catch (error) {
+            lastError = error;
+        }
+        try {
+            const stillExists = await vectorDatabase.hasCollection(collectionName);
+            if (!stillExists) {
+                return { collectionName, attempts: attempt, verifiedAbsent: true };
+            }
+            if (!lastError) {
+                lastError = new Error(`dropCollection returned successfully but '${collectionName}' still exists.`);
+            }
+        }
+        catch (error) {
+            lastError = error;
+        }
+        if (attempt < maxAttempts && initialBackoffMs > 0) {
+            await sleep(initialBackoffMs * Math.pow(backoffMultiplier, attempt - 1));
+        }
+    }
+    throw new RemoteCollectionDeletePendingError(collectionName, maxAttempts, lastError);
+}
+//# sourceMappingURL=remote-delete.js.map

package/dist/vectordb/types.d.ts

@@ -8,6 +8,14 @@ export interface VectorDocument {
     fileExtension: string;
     metadata: Record<string, any>;
 }
+export type RetrievalMode = 'dense' | 'lexical' | 'hybrid';
+export type ScorePolicy = {
+    kind: 'dense_similarity_min';
+    min: number;
+} | {
+    kind: 'topk_only';
+};
+export type BackendScoreKind = 'dense_similarity' | 'lexical_rank' | 'rrf_fusion';
 export interface SearchOptions {
     topK?: number;
     filter?: Record<string, any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-core",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "description": "Core semantic indexing engine for Satori's insight-first retrieval",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",