store

type Chunk struct {
	Seq         int
	HeadingPath string // "H1 > H2 > H3", empty for flat documents
	StartLine   int
	EndLine     int
	Text        string
	Context     string // LLM-generated situating context (contextual retrieval)
	TokenEst    int
}

type Document struct {
	ID         int64  `json:"-"`
	SourceName string `json:"source"`
	RelPath    string `json:"rel_path"` // path within the source, or generated id for managed docs
	URI        string `json:"uri"`      // file://..., git URL#branch:path, managed://<kb>/<id>
	Title      string `json:"title"`
	SHA256     string `json:"content_sha256"`
	SizeBytes  int64  `json:"size_bytes"`
	MtimeUnix  int64  `json:"mtime_unix"`
	// Metadata is a flat string map attached to the document (agent writes,
	// source annotations). Filterable at search time.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type DocumentContent struct {
	Document Document
	Text     string // reassembled from chunks in seq order
}

type Factory func(ctx context.Context, opts Options) (Store, error)

type FileState struct {
	SHA256    string
	SizeBytes int64
	MtimeUnix int64
}

type Hit struct {
	DocumentID  int64             `json:"document_id"`
	SourceName  string            `json:"source"`
	RelPath     string            `json:"rel_path"`
	URI         string            `json:"uri"`
	Title       string            `json:"title"`
	HeadingPath string            `json:"heading_path,omitempty"`
	StartLine   int               `json:"start_line"`
	EndLine     int               `json:"end_line"`
	Text        string            `json:"text"`
	Context     string            `json:"context,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
	Score       float64           `json:"score"`              // fused (RRF) or reranked score, higher is better
	FTSRank     int               `json:"fts_rank,omitempty"` // 1-based rank in the keyword result list, 0 if absent
	VecRank     int               `json:"vec_rank,omitempty"` // 1-based rank in the vector result list, 0 if absent
}

type Options struct {
	KBName     string
	ModelName  string
	Dimensions int
	// ProviderConfig is the raw per-provider config block from the YAML.
	ProviderConfig map[string]any
}

type Stats struct {
	Documents     int64
	Chunks        int64
	LastIndexedAt int64
}

type Store interface {
	// UpsertDocument replaces the document at (doc.SourceName, doc.RelPath)
	// with the given chunks and their embeddings, atomically.
	// len(chunks) must equal len(embeddings).
	UpsertDocument(ctx context.Context, doc Document, chunks []Chunk, embeddings [][]float32) error

	// DeleteDocument removes a document and its chunks. Deleting a document
	// that does not exist is not an error.
	DeleteDocument(ctx context.Context, sourceName, relPath string) error

	// Manifest returns the sync state of every tracked file for a source.
	Manifest(ctx context.Context, sourceName string) (map[string]FileState, error)

	// TouchManifest updates a file's manifest entry without reindexing, for
	// files whose size/mtime changed but whose content hash did not.
	TouchManifest(ctx context.Context, sourceName, relPath string, fs FileState) error

	// HybridSearch runs keyword and vector retrieval and fuses the results.
	// queryVec dimension must match the store's configured dimension.
	HybridSearch(ctx context.Context, query string, queryVec []float32, k int) ([]Hit, error)

	// GetDocument fetches one document by (sourceName, relPath). Returns
	// ErrNotFound if it does not exist. sourceName may be empty to search
	// across all sources of the KB (first match wins; rel paths are unique
	// per source).
	GetDocument(ctx context.Context, sourceName, relPath string) (*DocumentContent, error)

	// ListDocuments pages through documents ordered by rel_path. A prefix
	// filters by rel_path prefix; cursor is the last rel_path of the
	// previous page ("" for the first page).
	ListDocuments(ctx context.Context, prefix, cursor string, limit int) ([]Document, error)

	Stats(ctx context.Context) (Stats, error)

	Close() error
}