anystore

type AggQuery interface {
	// GroupLimit overrides the maximum number of unique $group keys
	// (default aggregate.DefaultGroupLimit; negative = unlimited).
	GroupLimit(n int) AggQuery

	// AccumArrayLimit overrides the maximum $push / $addToSet array length
	// (default aggregate.DefaultAccumArrayLimit; negative = unlimited).
	AccumArrayLimit(n int) AggQuery

	// MemoryLimit overrides the retained-bytes budget shared by the
	// pipeline's blocking stages — $group state and in-pipeline $sort
	// (default aggregate.DefaultMemoryLimit; negative = unlimited).
	MemoryLimit(bytes int) AggQuery

	// IndexHint adds or removes boost for indexes considered by the pushed
	// prefix's query plan.
	IndexHint(hints ...IndexHint) AggQuery

	// Iter executes the pipeline and returns an Iterator over result
	// documents. Score and Distance report 0 on aggregation iterators; for a
	// full-text or vector $match prefix the values remain available as the
	// _score / _distance document fields. See Iterator for the
	// mutation-while-iterating contract (undefined, SQLite-style).
	Iter(ctx context.Context) (Iterator, error)

	// Count executes the pipeline and returns the number of result documents.
	Count(ctx context.Context) (int, error)

	// Explain returns the access plan of the pushed prefix and the list of
	// in-pipeline stages.
	Explain(ctx context.Context) (Explain, error)
}

type CipherType = btree.CipherType

type Codec = btree.Codec

type Collection interface {
	// Name returns the name of the collection.
	Name() string

	// PrimaryKey returns the document field used as this collection's primary key.
	PrimaryKey() string

	// FindId finds a document by its ID.
	// Returns the document or an error if the document is not found.
	FindId(ctx context.Context, id any) (Doc, error)

	// FindIdWithParser finds a document by its ID. Uses provided anyenc parser.
	// Returns the document or an error if the document is not found.
	FindIdWithParser(ctx context.Context, p *anyenc.Parser, id any) (Doc, error)

	// Find returns a new Query object with given filter
	Find(filter any) Query

	// Aggregate returns a new aggregation query for the given MongoDB-style
	// pipeline (an array of stages like $match, $group, $sort, $unwind, ...).
	Aggregate(pipeline any) AggQuery

	// Insert inserts multiple documents into the collection.
	// Returns an error if the insertion fails.
	Insert(ctx context.Context, docs ...*anyenc.Value) (err error)

	// UpdateOne updates a single document in the collection.
	// Provided document must contain an id field
	// Returns an error if the update fails.
	UpdateOne(ctx context.Context, doc *anyenc.Value) (err error)

	// UpdateId updates a single document in the collection with provided modifier
	// Returns a modify result or error.
	UpdateId(ctx context.Context, id any, mod query.Modifier) (res ModifyResult, err error)

	// UpsertOne inserts a document if it does not exist, or updates it if it does.
	// Returns the ID of the upserted document or an error if the operation fails.
	UpsertOne(ctx context.Context, doc *anyenc.Value) (err error)

	// UpsertId updates a single document or creates new one
	// Returns a modify result or error.
	UpsertId(ctx context.Context, id any, mod query.Modifier) (res ModifyResult, err error)

	// DeleteId deletes a single document by its ID.
	// Returns an error if the deletion fails.
	DeleteId(ctx context.Context, id any) (err error)

	// Count returns the number of documents in the collection.
	// Returns the count of documents or an error if the operation fails.
	Count(ctx context.Context) (count int, err error)

	// CreateIndex creates a new index.
	// Returns an error if index exists or the operation fails.
	CreateIndex(ctx context.Context, info ...IndexInfo) (err error)

	// EnsureIndex ensures an index exists on the specified fields.
	// Returns an error if the operation fails.
	EnsureIndex(ctx context.Context, info ...IndexInfo) (err error)

	// DropIndex drops an index by its name.
	// Returns an error if the operation fails.
	DropIndex(ctx context.Context, indexName string) (err error)

	// GetIndexes returns a list of indexes on the collection: range indexes
	// followed by full-text indexes (a full-text Len is the number of indexed
	// documents). Vector indexes are not listed yet.
	GetIndexes() (indexes []Index)

	// CompactVectorIndex rebuilds the named vector index from its live vectors,
	// reclaiming nodes and storage left behind by deletes and replaces (which only
	// tombstone). It is synchronous and holds the write lock for the rebuild;
	// prefer a maintenance window for large indexes. No-op when nothing is
	// reclaimable or for a brute-force index. Returns ErrIndexNotFound if absent.
	CompactVectorIndex(ctx context.Context, indexName string) error

	// Stats returns the storage footprint of the collection: document count,
	// stored and uncompressed sizes, compression ratio and per-index sizes.
	// It scans the whole collection and is intended for diagnostics.
	Stats(ctx context.Context) (CollectionStats, error)

	// Rename renames the collection.
	// Returns an error if the operation fails.
	Rename(ctx context.Context, newName string) (err error)

	// Drop drops the collection.
	// Returns an error if the operation fails.
	Drop(ctx context.Context) (err error)

	// ReadTx starts a new read-only transaction. It's just a proxy to db object.
	// Returns a ReadTx or an error if there is an issue starting the transaction.
	ReadTx(ctx context.Context) (ReadTx, error)

	// WriteTx starts a new read-write transaction. It's just a proxy to db object.
	// Returns a WriteTx or an error if there is an issue starting the transaction.
	WriteTx(ctx context.Context) (WriteTx, error)

	// Close closes the collection.
	// Returns an error if the operation fails.
	Close() error
}

type CollectionOptions struct {
	// Compression overrides the database-wide compression setting for this collection.
	// Zero value inherits the database default.
	Compression Compression

	// PrimaryKey is the document field whose value is the collection's primary
	// key. Empty defaults to "id". Honored only at CreateCollection; the primary
	// key is immutable once the collection exists.
	PrimaryKey string
}

type CollectionStats struct {
	// Name is the collection name.
	Name string

	// DocCount is the number of documents in the collection.
	DocCount int

	// StoredDocsBytes is the sum of stored document value bytes. When
	// compression is enabled this counts the compressed form.
	StoredDocsBytes int

	// UncompressedDocsBytes is the sum of document value bytes after
	// decompression. It equals StoredDocsBytes when nothing is compressed.
	UncompressedDocsBytes int

	// CompressionEnabled reports whether compression is active for this
	// collection. Individual documents below anyenc.CompressMinSize are stored
	// uncompressed even when it is enabled.
	CompressionEnabled bool

	// CompressionRatio is UncompressedDocsBytes/StoredDocsBytes. It is 1.0 when
	// nothing is compressed and grows above 1.0 as compression saves space.
	CompressionRatio float64

	// DocsSizeBytes is the physical on-disk size of the collection's document
	// B-tree (page count including overflow pages times the page size).
	DocsSizeBytes int

	// IndexesSizeBytes is the sum of SizeBytes across all range (B-tree) indexes.
	IndexesSizeBytes int

	// VectorIndexesSizeBytes is the sum of SizeBytes across all vector indexes.
	VectorIndexesSizeBytes int

	// FtsIndexesSizeBytes is the sum of SizeBytes across all full-text indexes.
	FtsIndexesSizeBytes int

	// TotalSizeBytes is DocsSizeBytes + IndexesSizeBytes + VectorIndexesSizeBytes
	// + FtsIndexesSizeBytes.
	TotalSizeBytes int

	// Indexes holds per-(range-)index statistics.
	Indexes []IndexStats

	// VectorIndexes holds per-vector-index statistics.
	VectorIndexes []VectorIndexStats

	// FtsIndexes holds per-full-text-index statistics.
	FtsIndexes []FtsIndexStats
}

type Compression int

type Config struct {
	// SyncPoolElementMaxSize defines maximum size of buffer that can be returned to the syncpool
	// default value is 2MiB
	SyncPoolElementMaxSize int

	// CommitSync forces fsync on every WAL commit (like SQLite synchronous=FULL in WAL mode).
	// When false (default), fsync is deferred to checkpoint time, which reduces write latency
	// at the cost of losing the last committed transaction(s) on power loss.
	CommitSync bool

	// DisableAutoCheckpoint disables WAL auto-checkpoint entirely.
	// When true, checkpoint must be triggered manually or via durability auto-flush.
	DisableAutoCheckpoint bool

	// AutoCheckpointAfter overrides the default WAL auto-checkpoint threshold (10000 frames).
	// Only used when DisableAutoCheckpoint is false. 0 means use default.
	AutoCheckpointAfter int

	// CacheSize overrides the default per-DB page cache size (in pages,
	// default 5000). Primarily for tests that need to force pagerStress /
	// cache-spill behavior at low data volumes. Zero means use the default.
	CacheSize int

	// ReadConcurrency caps the number of concurrent read transactions. Reads
	// beyond this many serialize on a semaphore, so on a multi-core host a low cap
	// throttles concurrent Find/$text throughput. Each live reader holds its own
	// page cache (≈ CacheSize × PageSize), created lazily, so peak reader RAM is
	// ReadConcurrency × that — only realized under actual concurrent load. Zero
	// means the default, max(NumCPU-1, 4), which scales with the host while staying
	// modest on small devices.
	ReadConcurrency int

	// InMemory keeps the entire database in memory with no files on disk.
	// The database does not survive process crashes. When true, InProcess
	// and CommitSync=false are forced on automatically.
	// The path argument to Open is ignored and can be any string (e.g. ":memory:").
	InMemory bool

	// DisableCompression disables S2 compression for document values.
	// By default, objects larger than 256 bytes are compressed with S2.
	DisableCompression bool

	// UseGlobalPageBuffer opts this DB into the global pre-allocated page
	// buffer pool. The pool must be initialized beforehand via InitPageBuffer.
	// When false (default), page buffers use sync.Pool (GC-managed, like
	// SQLite's default malloc mode).
	UseGlobalPageBuffer bool

	// MmapSize enables mmap-backed reads of the database file up to the
	// given byte limit. Zero (default) disables mmap — reads use pread
	// via ReadAt, same behavior as before this feature existed.
	// Matches SQLite's PRAGMA mmap_size. Linux/darwin + amd64/arm64
	// only; no-op on other platforms.
	//
	// SAFETY WARNINGS — read before enabling:
	//
	//   - SIGBUS on unreachable storage: if the DB file becomes
	//     truncated, unlinked, or the storage device is removed while
	//     a mapping is live (USB unplug, iCloud eviction of a
	//     "dataless" file, NFS server timeout, external process
	//     truncate), accessing the mapped bytes generates SIGBUS. Go's
	//     runtime translates SIGBUS to an uncatchable "unexpected
	//     fault address" crash — the whole process dies. The pread
	//     path (MmapSize=0) returns a normal error for all of these
	//     scenarios. Only enable on paths you control: local disk,
	//     stable filesystem, single-device. Do NOT enable for DBs
	//     stored in iCloud Drive, OneDrive, Dropbox, or any network
	//     mount.
	//
	//   - Mobile / iOS: mmap'd bytes count against the per-process
	//     memory limit and can trip iOS's "jetsam" reaper on older
	//     devices. iOS may also silently purge mmap pages under
	//     memory pressure; re-faulting succeeds for local files but
	//     fails (SIGBUS) if the backing file has become unavailable
	//     (permission revocation, iCloud eviction). Recommend leaving
	//     at zero on iOS/iPadOS unless you have a measured need.
	//
	//   - Network filesystems: mmap coherence over NFS/SMB is weaker
	//     than over local disks; concurrent writes from peers may be
	//     invisible to the mapping, and reads may observe torn state.
	//     pread does not have this issue.
	//
	// Recommended when it IS safe: 64-512 MiB on workloads with
	// frequent large-blob or repeat-page reads, on stable local
	// storage, desktop/server deployments.
	MmapSize int64

	// DurabilityConfig provides configuration for crash recovery and idle auto-flush
	Durability DurabilityConfig

	// Encryption, when non-empty, enables page-level AES-256-GCM encryption
	// of the on-disk database file. Zero value means no encryption.
	Encryption EncryptionConfig

	// OnIntegrityError, when non-nil, is invoked from the read path on
	// every per-page integrity failure (XXH3 trailer mismatch in cksum
	// mode, AEAD auth-tag failure in encryption mode). Plain databases
	// never fire it.
	//
	// The callback runs synchronously on the I/O goroutine and must not
	// block. Push to a buffered channel + drain elsewhere if you need
	// retention or cross-thread delivery.
	//
	// Set this at Open time so failures discovered during the first
	// page-1 read (which happens inside Open) are observable. There is
	// no post-Open setter — the codebase favors config-at-Open over
	// runtime mutation.
	OnIntegrityError func(IntegrityError)

	// ContinueOnIntegrityError, when true, lets reads of corrupt pages
	// return their (potentially garbage) bytes instead of erroring with
	// ErrPageIntegrity. The OnIntegrityError callback still fires —
	// only the error-return is suppressed. Mirror of cksumvfs's
	// `PRAGMA checksum_verification = OFF`.
	//
	// Default (false) is the safe choice: corrupt pages cause reads to
	// fail, callers see the error, app halts or recovers. Enable only
	// for forensic dumps where you'd rather read garbage than not be
	// able to read at all.
	//
	// Honored only in checksum mode. AEAD-encrypted databases ignore
	// this flag (disabling AEAD verification would return attacker-
	// controlled plaintext, defeating the cipher).
	ContinueOnIntegrityError bool
}

type DB interface {
	// CreateCollection creates a new collection with the specified name.
	// Returns the created Collection or an error if the collection already exists.
	// Possible errors:
	// - ErrCollectionExists: if the collection already exists.
	CreateCollection(ctx context.Context, collectionName string, opts ...CollectionOptions) (Collection, error)

	// OpenCollection opens an existing collection with the specified name.
	// Returns the opened Collection or an error if the collection does not exist.
	// Possible errors:
	// - ErrCollectionNotFound: if the collection does not exist.
	OpenCollection(ctx context.Context, collectionName string) (Collection, error)

	// Collection is a convenience method to get or create a collection.
	// It first attempts to open the collection, and if it does not exist, it creates the collection.
	// Returns the Collection or an error if there is an issue creating or opening the collection.
	Collection(ctx context.Context, collectionName string, opts ...CollectionOptions) (Collection, error)

	// GetCollectionNames returns a list of all collection names in the database.
	// Returns a slice of collection names or an error if there is an issue retrieving the names.
	GetCollectionNames(ctx context.Context) ([]string, error)

	// Stats returns the statistics of the database.
	// Returns a DBStats struct containing the database statistics or an error if there is an issue retrieving the stats.
	Stats(ctx context.Context) (DBStats, error)

	// QuickCheck performs a quick integrity check. If result not ok returns error.
	QuickCheck(ctx context.Context) (err error)

	// IntegrityCheck runs the full structural btree integrity check:
	// reachable-page coverage, orphan detection, freelist consistency,
	// overflow-chain validation, key ordering, and master-page consistency.
	// Returns nil if the database is structurally consistent, or an error
	// aggregating up to 100 issues found. More expensive than QuickCheck —
	// intended for stress tests and offline diagnostics, not normal opens.
	IntegrityCheck(ctx context.Context) (err error)

	// Flush perform checkpoint on the btree database
	// When waitIdleDuration > 0, wait for waitIdleTime since the last write tx got released
	Flush(ctx context.Context, waitIdleDuration time.Duration, mode FlushMode) error

	// Backup creates a backup of the database at the specified file path.
	// Returns an error if the operation fails.
	Backup(ctx context.Context, path string) (err error)

	// ReadTx starts a new read-only transaction.
	// Returns a ReadTx or an error if there is an issue starting the transaction.
	ReadTx(ctx context.Context) (ReadTx, error)

	// WriteTx starts a new read-write transaction.
	// Returns a WriteTx or an error if there is an issue starting the transaction.
	WriteTx(ctx context.Context) (WriteTx, error)

	// Close closes the database connection.
	// Returns an error if there is an issue closing the connection.
	Close() error

	// IntegrityMode reports the page-level integrity mode of this database
	// (none / checksum / AEAD).
	IntegrityMode() IntegrityMode

	// VerifyIntegrity walks every page and verifies its per-page integrity
	// tag (XXH3-128 trailer for cksum mode, AEAD auth tag for encrypted mode).
	// Plain DBs return IntegrityNone with zero pages scanned. Mismatches are
	// returned in IntegrityReport.Errors; the function only errors on I/O or
	// context cancellation. See IntegrityConfig.
	VerifyIntegrity(ctx context.Context) (IntegrityReport, error)
}

type DBStats struct {
	// CollectionsCount is the total number of collections in the database.
	CollectionsCount int

	// IndexesCount is the total number of indexes across all collections in the database.
	IndexesCount int

	// TotalSizeBytes is the total size of the database in bytes.
	TotalSizeBytes int

	// DataSizeBytes is the total size of the data stored in the database in bytes, excluding free space.
	DataSizeBytes int

	DirtyOnOpen             bool          // indicates we have sentinel file on open
	DirtyQuickCheckDuration time.Duration // time spent in quickcheck if dirty
}

type Doc interface {
	// Value returns the document as a *anyenc.Value.
	// Important: When used in an iterator, the returned value is valid only until the next call to Next.
	Value() *anyenc.Value
}

type DurabilityConfig struct {
	// Enable auto-flush according to IdleAfter and FlushMode
	AutoFlush bool

	// IdleAfter is the duration to wait after the last write before performing autoflush
	// Default: 20s
	IdleAfter time.Duration

	// FlushMode specifies how to autoflush data during idle periods
	// Default: FlushModeCheckpointPassive
	FlushMode FlushMode

	// Sentinel enables the sentinel file (.lock) that tracks database dirty state
	// When true (default is false), the sentinel file is used to detect unclean shutdowns and perform QuickCheck on open
	Sentinel bool
}

type EncryptionConfig struct {
	// Passphrase is the user-supplied secret. Nil = no encryption.
	Passphrase []byte

	// KDFIterations overrides the PBKDF2 cost. Zero means 256,000 (the
	// SQLCipher v4 default). Ignored when Passphrase is exactly 32 bytes
	// (raw-key path). Use lower values only in tests.
	KDFIterations int

	// CipherType selects the built-in AEAD when Passphrase is set.
	// Zero value (CipherAES256GCM) is the default.
	CipherType CipherType

	// Codec, when non-nil, bypasses Passphrase / KDFIterations / CipherType
	// and is used verbatim. Use this for HSM-backed or other externally-
	// keyed codecs.
	Codec Codec
}

type Explain struct {
	Sql string

	// Rich explain output: multi-line plan with cost breakdown and candidates
	Plan string

	Indexes []IndexExplain
}

type File = btree.File

type FlushMode string

type FtsIndexStats struct {
	// Name is the index name; Fields are the indexed text fields.
	Name   string
	Fields []string

	// DocCount is the number of documents currently indexed (documents with no
	// indexable text are excluded). VocabSize is the number of distinct terms.
	// TotalTokens is the sum of all document lengths in tokens; AvgDocLen is the
	// mean (TotalTokens/DocCount) — the BM25 length-normalization baseline.
	DocCount    int
	VocabSize   int
	TotalTokens int
	AvgDocLen   float64

	// PostingsBytes / VocabBytes / DocmapBytes / DocinfoBytes / MetaBytes are the
	// on-disk sizes of the five namespaces (the postings dominate).
	PostingsBytes int
	VocabBytes    int
	DocmapBytes   int
	DocinfoBytes  int
	MetaBytes     int

	// SizeBytes is the total physical size of the index (sum of the five).
	SizeBytes int
}

type FulltextParams struct {
	// Weights is the per-field BM25F boost, keyed by indexed field name (each key
	// must be one of IndexInfo.Fields). A field absent from the map has weight 1.0.
	// Mirrors MongoDB's text-index weights option, but scoring is BM25F: the
	// per-field term frequencies are combined as Σ weight_f · tf_f and then scored
	// with standard BM25 saturation + length normalization. Set at index creation;
	// changing a weight only changes ranking (no re-index needed — weights are read
	// at query time). Boosting e.g. {"title": 5} ranks title matches above body.
	Weights map[string]float64 `json:"weights,omitempty"`
	// B is the BM25 length-normalization parameter, in [0,1]. 0 ⇒ the default
	// 0.75. Lower values reduce the bias toward short documents (e.g. 0.4 is a
	// reasonable choice for a corpus of mixed-length notes); 0 disables length
	// normalization entirely — but note 0 is read as "use the default", so to
	// approach no normalization use a small value rather than exactly 0.
	B float64 `json:"b,omitempty"`
	// K1 is the BM25 term-frequency saturation parameter (>= 0). 0 ⇒ the default
	// 1.2. Higher values make repeated term occurrences count for more.
	K1 float64 `json:"k1,omitempty"`
}

type Index interface {
	// Info returns the IndexInfo for this index.
	Info() IndexInfo

	// Len returns the length of the index.
	Len(ctx context.Context) (int, error)
}

type IndexExplain struct {
	Name string
	Cost float64 // CBO computed cost
	Used bool
}

type IndexHint struct {
	IndexName string
	Boost     int
}

type IndexInfo struct {
	// Name is the name of the index. If empty, it will be generated
	// based on the fields (e.g., "name,-createdDate").
	Name string `json:"name"`

	// Fields are the fields included in the index. Each field can specify
	// ascending (e.g., "name") or descending (e.g., "-createdDate") order.
	Fields []string `json:"fields"`

	// Unique indicates whether the index enforces a unique constraint.
	Unique bool `json:"unique"`

	// Sparse indicates whether the index is sparse, indexing only documents
	// with a present, non-null value for every indexed field.
	//
	// Null is treated the same as missing: a document whose indexed field is
	// explicitly null is NOT indexed (this differs from MongoDB, where a sparse
	// index stores present-but-null values). The choice keeps sparse indexing
	// consistent with query matching, where {field: null} matches both a null
	// and a missing field.
	//
	// As a consequence, the planner only uses a sparse index for a query that
	// guarantees every indexed field is present and non-null; otherwise it would
	// silently drop matching documents the index never stored. In particular a
	// query whose only constraint on a field is {$exists: true} cannot use a
	// sparse index here, because an explicit-null document matches $exists:true
	// yet is absent from the index — such a query falls back to a complete index
	// or a full scan. For a unique sparse index, several documents with a missing
	// or null field coexist freely, since none of them are indexed.
	Sparse bool `json:"sparse"`

	// Kind selects the index type (range by default, full-text, or vector).
	Kind IndexKind `json:"kind,omitempty"`

	// Fulltext configures a full-text index when Kind == IndexKindFulltext.
	Fulltext *FulltextParams `json:"fulltext,omitempty"`

	// Vector configures a vector index when Kind == IndexKindVector.
	Vector *VectorParams `json:"vector,omitempty"`
}

type IndexKind uint8

type IndexSketchInfo struct {
	Size     int      // buckets per level; normally qplanner.DefaultSketchSize
	Levels   int      // number of prefix levels (= number of index fields)
	DocCount uint64   // total documents tracked by this index
	Buckets  []uint64 // per-bucket frequency counts, len == Size*Levels; level L is Buckets[L*Size:(L+1)*Size]
}

type IndexSketchInspector interface {
	InspectIndexSketch(ctx context.Context, collName, indexName string) (IndexSketchInfo, error)
}

type IndexStats struct {
	// Name is the index name.
	Name string

	// Fields are the indexed fields, with leading '-' marking descending order.
	Fields []string

	// Unique reports whether the index enforces a unique constraint.
	Unique bool

	// Sparse reports whether the index skips documents missing the fields.
	Sparse bool

	// EntryCount is the number of entries (key/value pairs) in the index B-tree.
	EntryCount int

	// PayloadBytes is the sum of key+value byte lengths across all entries.
	PayloadBytes int

	// SizeBytes is the physical on-disk size of the index B-tree, computed as
	// its page count (including overflow pages) times the database page size.
	SizeBytes int

	// SketchDocCount is the document count tracked by the index sketch.
	SketchDocCount uint64

	// SketchSize is the number of buckets in the index sketch.
	SketchSize int

	// SketchDistribution summarizes the sketch's bucket frequency distribution.
	SketchDistribution qplanner.SketchDistribution
}

type IntegrityError struct {
	PageNo uint32
	Kind   IntegrityErrorKind
	Inner  error
}

type IntegrityErrorKind int

type IntegrityMode int

type IntegrityReport struct {
	Mode   IntegrityMode
	Pages  int
	Errors []IntegrityError
}

type Iterator interface {
	// Next advances the iterator to the next document.
	Next() bool

	// Doc returns the current document.
	Doc() (Doc, error)

	// Distance returns the vector distance of the current document to the query
	// for a vector search (smaller is closer). It returns 0 for non-vector
	// queries.
	Distance() float32

	// Score returns the BM25 relevance score of the current document for a $text
	// search (larger is more relevant). It returns 0 for non-fts queries.
	Score() float64

	// Err returns any error encountered during the lifetime of the iterator.
	Err() error

	// Close closes the iterator and releases any associated resources.
	Close() error
}

type ModifyResult struct {
	// Matched is the number of documents matched by the query.
	Matched int

	// Modified is the number of documents that were actually modified.
	Modified int
}

type PipelinePerfCounters struct {
	Planner qplanner.PerfCounters

	DocCalls           uint64
	DocParsedHits      uint64
	DocFallbacks       uint64
	DocFallbackSeekNs  uint64
	DocFallbackParseNs uint64
}

type Query interface {

	// Limit sets the maximum number of documents to return.
	Limit(limit uint) Query

	// Offset sets the number of documents to skip before starting to return results.
	Offset(offset uint) Query

	// Sort sets the sort order for the query results.
	Sort(sort ...any) Query

	// IndexHint adds or removes boost for some indexes
	IndexHint(hints ...IndexHint) Query

	// Iter executes the query and returns an Iterator for the results. See
	// Iterator for the mutation-while-iterating contract (undefined,
	// SQLite-style).
	Iter(ctx context.Context) (Iterator, error)

	// Count returns the number of documents matching the query.
	Count(ctx context.Context) (count int, err error)

	// Update modifies documents matching the query.
	Update(ctx context.Context, modifier any) (res ModifyResult, err error)

	// Delete removes documents matching the query.
	Delete(ctx context.Context) (res ModifyResult, err error)

	// Explain provides the query execution plan.
	Explain(ctx context.Context) (explain Explain, err error)
}

type ReadTx interface {
	// Context returns the context associated with the transaction.
	Context() context.Context

	// Commit commits the transaction.
	// Returns an error if the commit fails.
	Commit() error

	// Done returns true if the transaction is completed (committed or rolled back).
	Done() bool
	// contains filtered or unexported methods
}

type VFS = btree.VFS

type VectorIndexStats struct {
	// Name is the index name.
	Name string

	// Field is the indexed embedding field path.
	Field string

	// Dim is the embedding dimension; Metric is the distance metric.
	Dim    int
	Metric string
	// Mode is the index strategy ("btree" | "hybrid" | "brute").
	Mode string
	// Quantization is the stored vector format ("none" | "int8").
	Quantization string

	// M / EfSearch are the HNSW graph parameters.
	M        int
	EfSearch int

	// NodeCount is the number of nodes ever allocated (including tombstones);
	// LiveCount excludes tombstones; DeletedCount is the tombstone count. A high
	// DeletedCount/NodeCount ratio signals that a compaction/rebuild is due.
	NodeCount    int
	LiveCount    int
	DeletedCount int

	// VectorBytes / GraphBytes / MappingBytes / MetaBytes are the on-disk sizes
	// of the vector, adjacency, docId<->label, and meta namespaces respectively.
	VectorBytes  int
	GraphBytes   int
	MappingBytes int
	MetaBytes    int

	// SizeBytes is the total physical size of the index (sum of the above).
	SizeBytes int
}

type VectorMetric uint8

type VectorMode uint8

type VectorParams struct {
	// Field is the path to the embedding field (an array of numbers).
	Field string `json:"field"`
	// Dim is the embedding dimension.
	Dim int `json:"dim"`
	// Metric is the distance measure (default cosine).
	Metric VectorMetric `json:"metric"`
	// M / EfConstruction / EfSearch tune the HNSW graph; 0 = sensible defaults.
	M              int `json:"m,omitempty"`
	EfConstruction int `json:"efConstruction,omitempty"`
	EfSearch       int `json:"efSearch,omitempty"`
	// Quantization selects the stored vector format (default full float32). For
	// VectorModeIVFPQ it sets the format of the re-rank vector store (the bulk of the
	// index): VectorQuantInt8 makes it ~4× smaller on disk and in the page cache —
	// cutting RAM and speeding the random per-candidate re-rank reads — at ~0.5%
	// recall, and is recommended there.
	Quantization VectorQuantization `json:"quantization,omitempty"`
	// Mode selects the index strategy (default btree). See VectorMode.
	Mode VectorMode `json:"mode,omitempty"`
	// HybridCacheVectors, for VectorModeHybrid, also caches vectors in RAM (the
	// "vector tier") so layer-0 search avoids btree vector reads entirely — the
	// bulk of search cost. RAM ≈ liveVectors × recordSize (use int8 to keep it
	// small). Ignored unless Mode == VectorModeHybrid.
	HybridCacheVectors bool `json:"hybridCacheVectors,omitempty"`

	// CompactRatio enables automatic compaction of the HNSW graph. Deletes and
	// replaces only tombstone nodes; when tombstones reach CompactRatio × live
	// nodes, the index is rebuilt to reclaim them (dropping dead nodes, superseded
	// vectors, and re-densifying labels). 0 (the default) disables auto-compaction
	// — the index is then only compacted via Collection.CompactVectorIndex.
	//
	// Choosing a value (measured — see TestVectorCompactThreshold): tombstoned
	// nodes are still traversed during search, so latency rises roughly linearly
	// with the deleted/live ratio (recall does NOT — it holds/improves as the live
	// set shrinks). Search latency degrades ~30% at a ratio of ~0.2–0.25, ~50% at
	// ~0.5, and ~2x at ~1.0 (steeper at larger N / higher dim). With
	// HybridCacheVectors, tombstones also inflate the RAM vector tier (it tracks
	// the label high-water mark, not the live set), so compaction reclaims RAM too.
	// A rebuild costs ~one re-insert of the live set, so the amortized compaction
	// cost per delete is ~insertCost / CompactRatio — i.e. a smaller ratio caps
	// latency tighter but rebuilds far more often. Balanced default: ~0.5. Use
	// ~0.25 only for read-latency-sensitive, delete-light workloads.
	//
	// Auto-compaction runs synchronously, in its own transaction, right after the
	// self-contained write that crosses the threshold — never inside a
	// caller-managed transaction. The rebuild is O(live) at ~850 nodes/s for dim
	// 768 (measured, see TestVectorCompactTiming): ~23 s to rebuild 19k live, ~45 s
	// for 38k. It surfaces as a latency spike on the triggering write, so for large
	// indexes prefer leaving this 0 and scheduling Collection.CompactVectorIndex in
	// a maintenance window.
	// Ignored for VectorModeBruteForce.
	//
	// For VectorModeIVFPQ, CompactRatio instead bounds *centroid drift*: IVF deletes
	// are physical (no tombstones), but the codebooks are frozen at build, so as the
	// data distribution shifts the partition degrades. CompactRatio triggers an
	// automatic rebuild (re-train from the live set) when the drift score —
	// max(reconstruction-error ratio − 1, churn ratio) — reaches it. ~0.5 rebuilds
	// after the live set roughly doubles or new data fits the centroids ~50% worse;
	// 0 disables auto-rebuild (use Collection.CompactVectorIndex manually).
	CompactRatio float64 `json:"compactRatio,omitempty"`

	// IVF-PQ parameters (Mode == VectorModeIVFPQ only). Zero values pick defaults.
	//
	// NList is the number of coarse cells (k-means centroids); 0 ⇒ ~4·√N at build.
	// More cells = finer partition = fewer vectors scanned per probe, but more
	// centroids to compare and a larger training requirement.
	NList int `json:"nList,omitempty"`
	// NProbe is how many cells a search scans (the recall/speed dial); 0 ⇒ 16.
	// Higher = more recall, more cells scanned.
	NProbe int `json:"nProbe,omitempty"`
	// Closure is the multi-assignment factor: each vector is placed in its Closure
	// nearest cells (with a per-cell residual code) so boundary vectors are found at
	// lower NProbe (SPANN closure). 0/1 = single assignment; ~4 reaches parity at
	// ~4× lower NProbe, costing ~Closure× the on-disk code bytes. M (above) sets the
	// number of PQ subquantizers / code bytes; Dim must be divisible by M.
	Closure int `json:"closure,omitempty"`
	// PrecomputeTableMiB budgets the RAM for the IVF-PQ precomputed ADC table, which
	// removes the per-cell distance-table rebuild from search (measured ~3× faster
	// search at dim 768) at the cost of an always-resident table of nlist·M·1 KiB.
	// 0 = the default budget (128 MiB: on for typical indexes, off for very large
	// ones whose table would exceed it); a negative value disables the table
	// (smallest RAM, slower search); a positive value sets the budget in MiB.
	PrecomputeTableMiB int `json:"precomputeTableMiB,omitempty"`
}

type VectorQuantization uint8

type WriteTx interface {
	// ReadTx is embedded to provide read-only transaction methods.
	ReadTx
	// Rollback rolls back the transaction.
	// Returns an error if the rollback fails.
	Rollback() error

	// SetModified marks the transaction as having made modifications
	// used internally for sentinel mechanism
	SetModified()
	// contains filtered or unexported methods
}