search

type AnalyzerMismatchError struct {
	Collection string
	Field      string // "analyzer_version" | "scoring_model"
	Existing   string
	Requested  string
}

type Change struct {
	Merge  map[string]any `json:"merge,omitempty"`
	Fields *FieldSet      `json:"fields,omitempty"`
}

type CodedError interface {
	error
	Code() string
}

type Collection struct {
	Name            string `json:"name"`
	AnalyzerVersion string `json:"analyzer_version"`
	ScoringModel    string `json:"scoring_model"`
	// Records is filled by DescribeCollection and ListCollections.
	Records uint64 `json:"records"`
}

type CollectionNotFoundError struct {
	Tenant     string
	Collection string
}

type Condition = vector.Condition

type Config struct {
	// Path is the bundled backend's root directory (--search-path).
	Path string
	// MaxOpenIndexes bounds how many collection indexes the bundled backend
	// holds open at once (--search-max-open-indexes). Zero takes its default.
	MaxOpenIndexes int
}

type Constructor func(Config) (Store, error)

type FieldSet struct {
	Name    *string `json:"name,omitempty"`
	Title   *string `json:"title,omitempty"`
	Heading *string `json:"heading,omitempty"`
}

type Filter = vector.Filter

type Hit struct {
	ID       string         `json:"id"`
	Rank     int            `json:"rank"`
	Text     string         `json:"text"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type InvalidArgError struct{ Reason string }

type Item struct {
	ID       string         `json:"id"`
	Text     string         `json:"text,omitempty"`
	Title    string         `json:"title,omitempty"`
	Heading  string         `json:"heading,omitempty"`
	Name     string         `json:"name,omitempty"`
	Entities []string       `json:"entities,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type Manifest struct {
	Tenant          string `json:"tenant"`
	Collection      string `json:"collection"`
	AppliedSeq      uint64 `json:"applied_seq"`
	Records         uint64 `json:"records"`
	AnalyzerVersion string `json:"analyzer_version"`
	ScoringModel    string `json:"scoring_model"`
	Engine          string `json:"engine"`
	CreatedAt       string `json:"created_at"`
}

type Mutation struct {
	Op         MutationOp `json:"op"`
	Collection Collection `json:"collection,omitempty"` // ensure
	Items      []Item     `json:"items,omitempty"`      // upsert
	Select     Selector   `json:"select,omitempty"`     // delete
	Filter     Filter     `json:"filter,omitempty"`     // update
	Change     Change     `json:"change,omitempty"`     // update
}

type MutationOp string

type RecoveringError struct{ Reason string }

type Selector struct {
	IDs    []string `json:"ids,omitempty"`
	Filter Filter   `json:"filter,omitempty"`
}

type Sequenced interface {
	// ApplyAt applies m to the collection unless the collection has already
	// applied a mutation at seq or later, in which case it does nothing and
	// reports applied == false. The position is stored in the same write as
	// the mutation's last change, so after a crash a collection is never
	// ahead of, or behind, the position it reports. A replay of the same log
	// from any earlier point therefore converges on the same records.
	//
	// OpEnsure creates the collection, OpDrop removes it, and the other ops
	// need it to exist (CollectionNotFoundError otherwise). count is what the
	// matching Store method would have returned.
	ApplyAt(ctx context.Context, tenant, collection string, seq uint64, m Mutation) (count int, applied bool, err error)

	// AppliedSeq reports the position of the last mutation the collection
	// applied. found is false when the collection is not on this node's disk.
	AppliedSeq(ctx context.Context, tenant, collection string) (seq uint64, found bool, err error)
}

type Snapshotter interface {
	// StagingDir is a scratch directory on the same filesystem as the store,
	// so that Install can move a snapshot into place instead of copying it.
	StagingDir() (string, error)

	// Snapshot writes a complete, self-contained copy of the collection into
	// dir, which must not exist. The collection stays open and writable
	// meanwhile. The copy is opened and checked before Snapshot returns, and
	// the manifest records what it actually holds, not what was asked for.
	Snapshot(ctx context.Context, tenant, collection, dir string) (Manifest, error)

	// Install makes the snapshot at dir (as written by Snapshot) this store's
	// copy of the collection, replacing any it has. dir is consumed.
	Install(ctx context.Context, tenant, collection, dir string) (Manifest, error)
}

type Store interface {
	// EnsureCollection creates the collection if absent and is a no-op if it
	// exists. c.AnalyzerVersion and c.ScoringModel may be left empty to take
	// the backend's; a value that differs from an existing collection's pin,
	// or that the backend cannot provide, returns AnalyzerMismatchError.
	EnsureCollection(ctx context.Context, tenant string, c Collection) error

	// DescribeCollection returns the pinned collection and its record count.
	// found is false (nil error) when it doesn't exist.
	DescribeCollection(ctx context.Context, tenant, name string) (c Collection, found bool, err error)

	// Upsert inserts or replaces items by ID, all or nothing. Returns the
	// number of items written.
	Upsert(ctx context.Context, tenant, collection string, items []Item) (int, error)

	// Query returns up to limit hits for q among the records filter admits,
	// best first. q is plain language: a quoted string is a phrase, an
	// identifier is matched whole, and the rest is OR-ed. No engine syntax is
	// recognised. An empty result is not an error.
	Query(ctx context.Context, tenant, collection, q string, limit int, filter Filter) ([]Hit, error)

	// Delete removes the records sel names. Returns the number removed, or
	// CountPending.
	Delete(ctx context.Context, tenant, collection string, sel Selector) (int, error)

	// Update applies ch to every record filter admits, leaving text alone.
	// filter must carry at least one condition: an unconditional rewrite is
	// refused with InvalidArgError. The filter is evaluated when the update is
	// applied. Returns the number of records matched, or CountPending.
	Update(ctx context.Context, tenant, collection string, filter Filter, ch Change) (int, error)

	// ListCollections returns the tenant's collections, sorted by name. Not a
	// hot path.
	ListCollections(ctx context.Context, tenant string) ([]Collection, error)

	// DropCollection removes a collection and all its records, returning the
	// number of records removed. A missing collection is not an error
	// (returns 0).
	DropCollection(ctx context.Context, tenant, name string) (int, error)

	// Shared reports whether this backend is shared across nodes, versus
	// per-node. The bundled backend is per-node (returns false).
	Shared() bool

	// Close flushes and releases the backend. A search index must be closed.
	Close() error
}

type TooLargeError struct {
	What  string
	Got   int
	Limit int
}

type UnavailableError struct{ Reason string }