import { type RagChunk, type RagRetrievalResult, type RagSourceKind } from '../types/sparkContracts';
import { type KnowledgeScope } from './scopedKnowledgeStore';
export interface RagStoreSearchOptions {
    /** Maximum hits returned. Defaults to 5. */
    topK?: number;
    /** Restrict the search to a subset of source kinds. */
    kinds?: RagSourceKind[];
    /** Enterprise tenant/workspace scope. Ignored by legacy JSON storage. */
    scope?: KnowledgeScope;
    /** Restrict source-backed chunks to selected codebases. */
    codebaseIds?: string[];
    vendor?: string;
    buildId?: string;
    pathPrefix?: string;
    symbolExact?: string;
    filePathExact?: string;
    languages?: RagChunk['language'][];
}
/** Per-kind index summary returned by `getStats()`. */
export type RagStoreStats = Record<RagSourceKind, {
    chunkCount: number;
    lastIndexedAt?: number;
}>;
/**
 * Local file-backed RAG store. Single instance per storage path is
 * enough for M0 — concurrent writers in the same process serialize via
 * the synchronous persistence path; cross-process writers are not
 * supported (caller's responsibility to coordinate).
 */
export declare class RagStore {
    private readonly storagePath;
    private readonly chunks;
    private loaded;
    constructor(storagePath: string);
    /** Idempotently load the on-disk store into memory. */
    load(): void;
    /**
     * Add or replace a chunk. Throws when the kind requires a license and
     * the chunk lacks one — the caller is expected to surface this back
     * to the operator rather than silently dropping the chunk.
     */
    addChunk(chunk: RagChunk, scope?: KnowledgeScope): void;
    /** Remove a chunk. Returns whether anything was actually removed. */
    removeChunk(chunkId: string, scope?: KnowledgeScope): boolean;
    /** Get a chunk by id, or undefined when absent. */
    getChunk(chunkId: string, scope?: KnowledgeScope): RagChunk | undefined;
    /** Per-kind chunk counts plus the freshest indexedAt seen for each. */
    getStats(scope?: KnowledgeScope): RagStoreStats;
    /**
     * Keyword search. Hits are ranked by token-overlap fraction relative
     * to the query token set. Chunks carrying `unsupportedReason` are
     * excluded — they live on for audit but the agent must not see them.
     *
     * Three retrieval-level failure modes carry an `unsupportedReason`:
     * (1) the index is empty; (2) every chunk in the probed kinds is
     * blocked / out of scope; the third — a legitimate zero-match query —
     * intentionally returns an empty `results` array with NO
     * `unsupportedReason`, so the agent can tell "I didn't find anything"
     * apart from "the infrastructure refused to answer".
     */
    search(query: string, opts?: RagStoreSearchOptions): RagRetrievalResult;
    /** Flush in-memory chunks to disk. Call once after a bulk ingest loop. */
    flush(): void;
    /** Atomic write: temp file + rename so a crashed process leaves the
     * existing on-disk file intact. */
    private persist;
}
/** Whether the given source kind needs a `license` field at ingest time. */
export declare function ragStoreRequiresLicense(kind: RagSourceKind): boolean;
//# sourceMappingURL=ragStore.d.ts.map