import type { DistanceMetric } from './HNSWIndex.js';
/** JSON values accepted as collection metadata. */
export type JsonValue = string | number | boolean | null | JsonValue[] | {
    [key: string]: JsonValue;
};
/** A metadata object that can be persisted by Verso. */
export type Metadata = Record<string, JsonValue>;
/** Public vector input accepted by insert and search operations. */
export type VectorInput = number[] | Float32Array;
export type { DistanceMetric };
export type CollectionProfile = 'low-memory' | 'balanced' | 'high-recall' | 'low-latency';
export interface VectorSchema {
    dimensions: number;
    metric?: DistanceMetric;
}
export type MetadataFieldType = 'string' | 'number' | 'boolean' | 'string[]' | 'number[]' | 'boolean[]' | 'object' | 'any';
export interface MetadataFieldSchema {
    type: MetadataFieldType;
    index?: true | 'exact' | 'range' | 'contains' | false;
}
export type MetadataSchema = Record<string, MetadataFieldSchema | MetadataFieldType>;
/** Adapter shape supported by schema validators such as Zod or Valibot. */
export interface MetadataValidator<TMetadata = Metadata> {
    parse(value: unknown): TMetadata;
}
export type MetadataSchemaOption<TMetadata = Metadata> = MetadataSchema | MetadataValidator<TMetadata>;
export interface HNSWIndexConfig {
    type: 'hnsw';
    m?: number;
    efConstruction?: number;
    profile?: CollectionProfile;
}
export type IndexConfig = 'auto' | HNSWIndexConfig;
export interface CollectionConfig<TMetadata = Metadata> {
    vector: VectorSchema;
    index?: IndexConfig;
    profile?: CollectionProfile;
    metadataSchema?: MetadataSchemaOption<TMetadata>;
    /** Shorthand for a persisted descriptor schema. */
    metadata?: MetadataSchema;
}
export type CollectionSchema<TMetadata = Metadata> = CollectionConfig<TMetadata>;
export interface VectorRecordInput<TMetadata = Metadata> {
    id: string;
    vector: VectorInput;
    metadata?: TMetadata;
}
export interface VectorRecord<TMetadata = Metadata> {
    id: string;
    vector?: Float32Array;
    metadata?: TMetadata;
}
export interface InsertOptions {
    signal?: AbortSignal;
}
export interface InsertManyOptions extends InsertOptions {
    batchSize?: number;
    concurrency?: number | 'auto';
    onProgress?: (count: number) => void;
}
export interface ImportOptions extends InsertManyOptions {
    /** `insert` rejects existing IDs; `upsert` replaces them. */
    mode?: 'insert' | 'upsert';
}
export interface PackedInsert<TMetadata = Metadata> extends InsertOptions {
    ids: readonly string[];
    vectors: Float32Array;
    metadata?: readonly TMetadata[];
}
export interface UpdatePatch<TMetadata = Metadata> extends InsertOptions {
    /** Shallow-merged into the existing metadata object. */
    metadata?: Partial<TMetadata>;
    /** Replaces the vector while retaining the merged metadata. */
    vector?: VectorInput;
}
export interface UpdateManyRequest<TMetadata = Metadata> extends InsertOptions {
    filter?: Filter<TMetadata>;
    set: Partial<TMetadata>;
}
export interface IncludeOptions {
    metadata?: boolean;
    vector?: boolean;
}
export interface SearchTuning {
    efSearch?: number;
    quantization?: 'auto' | 'enabled' | 'disabled';
    oversampling?: number;
}
export type SearchAccuracy = 'fast' | 'balanced' | 'high' | 'exact';
export type SearchStrategy = 'auto' | 'exact' | {
    type: 'auto';
    accuracy?: SearchAccuracy;
} | {
    type: 'hnsw';
    efSearch?: number;
    quantization?: 'auto' | 'enabled' | 'disabled';
    oversampling?: number;
} | {
    type: 'exact';
};
export interface SearchStats {
    strategy: 'hnsw' | 'exact';
    visitedNodes?: number;
    candidateCount: number;
    filteredCandidates: number;
    exactRescoreCount?: number;
    quantizedTraversal: boolean;
    durationMs: number;
}
export interface SearchMatch<TMetadata = Metadata> {
    id: string;
    /** Metric-native distance. Lower is always better. */
    distance: number;
    /** Stable application-facing ranking score. Higher is always better. */
    score: number;
    metadata?: TMetadata;
    vector?: Float32Array;
    rank?: number;
}
export interface SearchResult<TMetadata = Metadata> {
    matches: Array<SearchMatch<TMetadata>>;
    stats?: SearchStats;
}
export type QueryOptions<TMetadata = Metadata> = SearchOptions<TMetadata>;
export type QueryMatch<TMetadata = Metadata> = SearchMatch<TMetadata>;
export type QueryResult<TMetadata = Metadata> = SearchResult<TMetadata>;
export interface SearchOptions<TMetadata = Metadata> {
    vector: VectorInput;
    limit: number;
    filter?: Filter<TMetadata>;
    include?: IncludeOptions;
    accuracy?: SearchAccuracy;
    strategy?: SearchStrategy;
    tuning?: SearchTuning;
    signal?: AbortSignal;
    explain?: boolean;
}
export interface SearchManyOptions extends InsertOptions {
    concurrency?: number | 'auto';
}
export interface ListOptions<TMetadata = Metadata> {
    limit?: number;
    cursor?: string;
    filter?: Filter<TMetadata>;
    include?: IncludeOptions;
    signal?: AbortSignal;
}
export interface ListPage<TMetadata = Metadata> {
    records: Array<VectorRecord<TMetadata>>;
    nextCursor?: string;
}
export interface GetOptions extends InsertOptions {
    include?: IncludeOptions;
}
export interface ScanOptions<TMetadata = Metadata> extends GetOptions {
    filter?: Filter<TMetadata>;
    batchSize?: number;
}
export interface DeleteRequest<TMetadata = Metadata> extends InsertOptions {
    ids?: readonly string[];
    filter?: Filter<TMetadata>;
    all?: boolean;
}
export interface CompactOptions extends InsertOptions {
    onProgress?: (progress: {
        phase: string;
        completed: number;
        total: number;
    }) => void;
}
export interface CompactResult {
    recordsBefore: number;
    recordsAfter: number;
    tombstonesRemoved: number;
    bytesBefore?: number;
    bytesAfter?: number;
    durationMs: number;
}
export interface CollectionDescription {
    name: string;
    count: number;
    deletedCount: number;
    vector: VectorSchema;
    index: {
        type: 'hnsw';
        m: number;
        efConstruction: number;
        quantization: {
            enabled: boolean;
        };
    };
    storage: {
        persisted: boolean;
        bytes?: number;
        dirty: boolean;
    };
    metadataSchema?: MetadataSchema;
}
export interface CollectionStats extends CollectionDescription {
    records: number;
    liveRecords: number;
    tombstones: number;
    dimensions: number;
    indexBytes?: number;
    metadataBytes?: number;
    quantizationEnabled: boolean;
    lastFlushedAt?: Date;
}
export interface VerificationReport {
    ok: boolean;
    records: number;
    tombstones: number;
    errors: string[];
}
export interface DurabilityBatchOptions {
    mode: 'batched';
    maxOperations?: number;
    maxDelayMs?: number;
}
export type Durability = 'immediate' | 'manual' | DurabilityBatchOptions;
export type StorageKind = 'auto' | 'file' | 'opfs' | 'memory';
export interface StorageOptions {
    type?: StorageKind;
    path?: string;
    namespace?: string;
    fallback?: 'error' | 'memory' | 'warn';
}
export interface StorageAdapter {
    readonly type?: string;
    read(key: string): Promise<ArrayBuffer | null>;
    write(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
    append?(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
    delete(key: string): Promise<void>;
    exists(key: string): Promise<boolean>;
    list(prefix?: string): Promise<string[]>;
    mkdir(path: string): Promise<void>;
}
export interface ConcurrencyOptions {
    /** OPFS uses the Web Locks API when available; file backends serialize in-process. */
    mode?: 'single-writer';
    lockTimeoutMs?: number;
}
export interface VectorDBOptions {
    path?: string;
    storage?: StorageOptions | 'memory' | StorageAdapter;
    durability?: Durability;
    workers?: 'auto' | number | {
        count: number;
    };
    concurrency?: ConcurrencyOptions;
}
export interface StorageStatus {
    kind: string;
    persistent: boolean;
    path?: string;
    namespace?: string;
    quota?: {
        usage?: number;
        available?: number;
    };
    workers?: number;
}
export interface DatabaseDescription {
    collections: number;
    storage: StorageStatus;
    names: string[];
}
export interface CollectionListOptions {
    includeStats?: boolean;
}
export interface CollectionListEntry extends CollectionDescription {
}
export interface Snapshot {
    version: 1;
    createdAt: string;
    entries: Record<string, unknown>;
    files: Record<string, Uint8Array>;
    checksum?: string;
}
export interface BackupOptions {
    /** Refuse to write into a non-empty destination unless explicitly enabled. */
    overwrite?: boolean;
}
export interface CollectionSnapshot<TMetadata = Metadata> {
    version: 1;
    collection: string;
    config: CollectionConfig<TMetadata>;
    files: Record<string, Uint8Array>;
    checksum?: string;
}
export interface WriteSession<TMetadata = Metadata> {
    insert(records: readonly VectorRecordInput<TMetadata>[], options?: InsertOptions): Promise<void>;
    upsert(records: readonly VectorRecordInput<TMetadata>[], options?: InsertOptions): Promise<void>;
    update(id: string, patch: UpdatePatch<TMetadata>): Promise<void>;
    delete(request: DeleteRequest<TMetadata>): Promise<number>;
}
export type SearchMethod<TMetadata = Metadata> = (options: SearchOptions<TMetadata>) => Promise<SearchResult<TMetadata>>;
/** A small typed filter language; unsupported operators are rejected at runtime. */
export type FieldFilter<T = unknown> = {
    $eq?: T;
    $ne?: T;
    $gt?: T;
    $gte?: T;
    $lt?: T;
    $lte?: T;
    $in?: readonly T[] | readonly unknown[];
    $nin?: readonly T[] | readonly unknown[];
    $exists?: boolean;
    $contains?: unknown;
    $containsAny?: readonly unknown[];
    $containsAll?: readonly unknown[];
    $startsWith?: string;
    $between?: readonly [T, T] | readonly [unknown, unknown];
};
export type FilterLogic<TMetadata = Metadata> = {
    $and?: readonly Filter<TMetadata>[];
    $or?: readonly Filter<TMetadata>[];
    $not?: Filter<TMetadata>;
};
export type Filter<TMetadata = Metadata> = {
    [K in keyof TMetadata]?: TMetadata[K] | FieldFilter<TMetadata[K]>;
} & FilterLogic<TMetadata>;
export interface WhereBuilder {
    eq<T = unknown>(field: string, value: T): Filter;
    ne<T = unknown>(field: string, value: T): Filter;
    gt<T = unknown>(field: string, value: T): Filter;
    gte<T = unknown>(field: string, value: T): Filter;
    lt<T = unknown>(field: string, value: T): Filter;
    lte<T = unknown>(field: string, value: T): Filter;
    in<T = unknown>(field: string, value: readonly T[]): Filter;
    nin<T = unknown>(field: string, value: readonly T[]): Filter;
    exists(field: string, value?: boolean): Filter;
    contains<T = unknown>(field: string, value: T): Filter;
    containsAny<T = unknown>(field: string, value: readonly T[]): Filter;
    containsAll<T = unknown>(field: string, value: readonly T[]): Filter;
    startsWith(field: string, value: string): Filter;
    between<T = unknown>(field: string, value: readonly [T, T]): Filter;
    and(...filters: Filter[]): Filter;
    or(...filters: Filter[]): Filter;
    not(filter: Filter): Filter;
}
export declare function defineCollection<TMetadata = Metadata>(config: CollectionConfig<TMetadata>): CollectionConfig<TMetadata>;
//# sourceMappingURL=public-api.d.ts.map