import { QmdSearchResult } from './types.js';

/** Alias so consumers don't need to reference "Qmd" in a backend-agnostic context. */
type SearchResult = QmdSearchResult;
interface SearchQueryOptions {
    intent?: string;
    explain?: boolean;
}
interface SearchExecutionOptions {
    signal?: AbortSignal;
}
/**
 * Abstract search backend interface.
 *
 * Implementations:
 * - QmdClient (default, local hybrid BM25+vector+reranking)
 * - OramaBackend (embedded, pure JS, hybrid FTS+vector)
 * - LanceDbBackend (embedded, native Arrow bindings, RRF reranking)
 * - MeilisearchBackend (server-based SDK, hybrid search)
 * - RemoteSearchBackend (HTTP REST adapter)
 * - NoopSearchBackend (graceful degradation)
 *
 * See docs/writing-a-search-backend.md for the implementation guide.
 */
interface SearchBackend {
    probe(): Promise<boolean>;
    isAvailable(): boolean;
    debugStatus(): string;
    search(query: string, collection?: string, maxResults?: number, options?: SearchQueryOptions, execution?: SearchExecutionOptions): Promise<SearchResult[]>;
    searchGlobal(query: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;
    bm25Search(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;
    vectorSearch(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;
    hybridSearch(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;
    update(execution?: SearchExecutionOptions): Promise<void>;
    updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;
    /**
     * Optional strict refresh used by callers that must know whether a collection
     * was actually refreshed before writing success markers. Ordinary update
     * calls remain fail-open for migration/maintenance resilience.
     */
    updateCollectionStrict?(collection: string, execution?: SearchExecutionOptions): Promise<void>;
    embed(): Promise<void>;
    embedCollection(collection: string): Promise<void>;
    ensureCollection(memoryDir: string): Promise<"present" | "missing" | "unknown" | "skipped">;
}

export type { SearchBackend as S, SearchQueryOptions as a, SearchExecutionOptions as b, SearchResult as c };
