/**
 * The contract suites the adapter kit ships: what every vector store, retriever, and long-term store
 * must do, as checks that need no test framework. Each check is named for the behavior it proves,
 * and a capability the adapter does not declare is reported as skipped, never as a failure.
 */
import type { RagChunk } from '../hallucination/rag.js';
import type { EmbeddingProvider, VectorStore } from '../hallucination/retrieval.js';
import type { Retriever } from '../rag/retrievers.js';
import type { Store } from '../types/store.js';
import type { AdapterKind } from './index.js';
/** One check of a contract suite. */
export interface AdapterCheck {
    /** What was checked, as a sentence. */
    name: string;
    /** Whether it held. */
    ok: boolean;
    /** Why it did not hold, or why it was skipped. */
    detail?: string;
    /** True when the adapter does not declare the capability the check needs. */
    skipped?: boolean;
}
/** One version of a kind's contract: the release it arrived in, and the checks it added. */
export interface AdapterContractVersion {
    /** The contract's version, counted from 1. */
    version: number;
    /** The release of `nexus-ai-pro` it arrived in. */
    nexus: string;
    /** The checks it added, by name. */
    added: readonly string[];
}
/** A kind's contract: its current version, and what each version added. */
export interface AdapterContract {
    /** The adapter kind it is for. */
    kind: AdapterKind;
    /** Its current version, which every record names. */
    version: number;
    /** Each version, oldest first, so a record verified against an older one says what it was not checked for. */
    history: readonly AdapterContractVersion[];
}
/**
 * Every kind's contract, versioned: a version is added when a release adds a check, so a record of
 * an adapter verified against an older version is known to be stale, and the checks it has not run are
 * named.
 */
export declare const ADAPTER_CONTRACTS: Readonly<Record<AdapterKind, AdapterContract>>;
/** The passages every retrieval contract runs on, and that benchmarks reuse. */
export declare const ADAPTER_FIXTURE_PASSAGES: readonly RagChunk[];
/** What a vector store declares it supports, for its contract. */
export interface VectorStoreCapabilities {
    /** `searchVector()` with a vector computed elsewhere. Defaults to true. */
    searchVector?: boolean;
    /** `minScore` drops weak matches. Defaults to true. */
    minScore?: boolean;
    /** Metadata filters: `exact` matches values, `typed` also tells `3` from `'3'`, `none` has no filters. Defaults to `exact`. */
    filters?: 'none' | 'exact' | 'typed';
}
/** Options for `runVectorStoreContract()`. */
export interface VectorStoreContractOptions {
    /** The embedding function the store was given, to compute a query vector for `searchVector()`. */
    embed: EmbeddingProvider;
    /** What the store supports. */
    capabilities?: VectorStoreCapabilities;
    /** Waits for writes to become searchable, for a store whose index is eventually consistent. */
    settle?: () => Promise<void>;
}
/**
 * The `VectorStore` contract: ranking, `topK`, sources and metadata round-tripped, filters,
 * `minScore`, vector search, replacement by id, deletes, an id added again after its delete, and
 * empty writes. The store should be empty
 * when it starts.
 */
export declare function runVectorStoreContract(store: VectorStore, options: VectorStoreContractOptions): Promise<AdapterCheck[]>;
/** What a retriever declares it supports, for its contract. */
export interface RetrieverCapabilities {
    /** It holds its own passages, with `add()` and `delete()`: a `SparseRetriever`. Defaults to whether it has them. */
    writes?: boolean;
    /** Metadata filters. Defaults to true. */
    filters?: boolean;
}
/** Options for `runRetrieverContract()`. */
export interface RetrieverContractOptions {
    /** What the retriever supports. */
    capabilities?: RetrieverCapabilities;
    /**
     * Loads the fixture passages, for a retriever that does not hold its own: into the vector store
     * behind it, say. A retriever with `add()` is loaded through that.
     */
    load?: (passages: RagChunk[]) => Promise<void>;
    /** Waits for writes to become searchable. */
    settle?: () => Promise<void>;
}
/**
 * The `Retriever` contract, and the `SparseRetriever` contract when the retriever takes writes:
 * an exact term found, ranking, `topK`, filters, replacement, deletes, and an empty query.
 */
export declare function runRetrieverContract(retriever: Retriever, options?: RetrieverContractOptions): Promise<AdapterCheck[]>;
/** What a long-term store declares it supports, for its contract. */
export interface StoreCapabilities {
    /** `search()` lists a namespace prefix, newest first. Defaults to true. */
    search?: boolean;
    /** `search()` filters on value fields. Defaults to true. */
    filters?: boolean;
    /** `listNamespaces()`. Defaults to true. */
    namespaces?: boolean;
}
/**
 * The long-term `Store` contract: values round-trip, a replaced item keeps its creation time, a
 * missing key reads as nothing, deletes, prefix search with filters and paging, and namespace
 * listing. The store should be empty when it starts.
 */
export declare function runStoreContract(store: Store, options?: {
    capabilities?: StoreCapabilities;
}): Promise<AdapterCheck[]>;