index

type ArmEvidence struct {
	// Rank is the zero-based position of the hit within the arm.
	Rank int
	// Score is the arm-native score at the time the arm returned the hit
	// (cosine derivative for vector, negative bm25 for FTS).
	Score float64
}

type BuildOptions struct {
	// Path is the OS-native filesystem path where the built snapshot
	// is written. On Windows both forward and back slashes are
	// accepted — the store package normalizes drive prefixes on open.
	Path string

	// ReuseFromPath points at an existing Stroma snapshot whose embeddings
	// should be reused at the section level: a new section reuses its
	// stored embedding whenever its title, heading, and body match a
	// section already present in the prior snapshot. Records that are
	// fully unchanged are the maximal case, but sections carried over
	// from an edited record still reuse their embeddings. The snapshot is
	// opened read-only and queried per-record during the rebuild, so
	// resident memory scales with a single record's chunks rather than
	// with the whole corpus. Leave empty to disable reuse.
	ReuseFromPath string

	Embedder embed.Embedder

	// Contextualizer optionally produces a per-chunk prefix string that
	// gets prepended before the embedding text and the FTS5 content. When
	// set, the prefix persists on the chunk and participates in reuse
	// keying so a changed contextualizer invalidates stale reuse without
	// corrupting the stored representation. Nil disables contextualization
	// and leaves the build identical to the non-contextual path.
	Contextualizer ChunkContextualizer

	// MaxChunkTokens sets the approximate maximum number of tokens (words)
	// per chunk. Sections that exceed this limit are split into smaller
	// sub-sections. Zero disables token-budget splitting.
	MaxChunkTokens int

	// ChunkOverlapTokens sets the approximate number of overlapping tokens
	// between adjacent sub-sections when a section is split. Zero disables
	// overlap.
	ChunkOverlapTokens int

	// MaxChunkSections caps how many sections any single record is allowed
	// to produce. A pathological Markdown body (e.g., 10^6 heading lines)
	// would otherwise translate into 10^6 embedder calls and 10^6
	// chunk/vector rows — a DoS vector for shared embedders. Zero means
	// DefaultMaxChunkSections; a negative value disables the cap for
	// callers who have their own upstream validation. When the cap is
	// exceeded, Rebuild returns an error wrapping chunk.ErrTooManySections
	// instead of silently admitting the record.
	MaxChunkSections int

	// Quantization controls the vector storage format. See the
	// store.Quantization* constants for the accept-listed values:
	// store.QuantizationFloat32 (default), store.QuantizationInt8 (4x
	// smaller, minor precision loss), and store.QuantizationBinary
	// (32x smaller via 1-bit sign packing, full-precision rescore on a
	// companion table preserves ranking).
	Quantization string

	// ChunkPolicy selects the chunking strategy. Nil defaults to
	// chunk.MarkdownPolicy{Options: chunk.Options{
	//     MaxTokens: MaxChunkTokens,
	//     OverlapTokens: ChunkOverlapTokens,
	//     MaxSections: <resolved>,
	// }}, which reproduces the pre-1.0 chunking pipeline exactly.
	// Setting a non-nil policy overrides the per-Build chunking shape:
	// MaxChunkTokens/ChunkOverlapTokens/MaxChunkSections are read by
	// the default MarkdownPolicy but ignored when ChunkPolicy is set
	// (the policy carries its own configuration). Hierarchical
	// policies like chunk.LateChunkPolicy emit parent + leaf chunks
	// linked via parent_chunk_id; ExpandContext can surface the
	// parent on demand. See docs/superpowers/specs for the design.
	ChunkPolicy chunk.Policy

	// IntegrityMode selects post-commit validation depth (#107). The
	// zero value, IntegrityModeFast, skips the SQLite-level whole-DB
	// PRAGMA passes that scale with total snapshot size; Stroma-specific
	// completeness checks still run. IntegrityModeFull adds the deep
	// PRAGMA passes for callers that want to validate the freshly built
	// snapshot against on-disk corruption before promoting it.
	IntegrityMode IntegrityMode
}

type BuildResult struct {
	Path                string
	RecordCount         int
	ChunkCount          int
	ReusedRecordCount   int
	ReusedChunkCount    int
	EmbeddedChunkCount  int
	ReuseStatus         ReuseStatus
	ReuseDisabledReason string
	EmbedderDimension   int
	EmbedderFingerprint string
	ContentFingerprint  string
}

type ChunkContextualizer interface {
	ContextualizeChunks(ctx context.Context, record corpus.Record, sections []chunk.Section) ([]string, error)
}

type ContextOptions struct {
	// IncludeParent walks the requested chunk's parent_chunk_id one level
	// up and includes the parent row in the returned slice when the chunk
	// has a parent. Multi-level ancestry walks are explicit recursion by
	// the caller.
	//
	// Against snapshots built before schema v5 (#16), there is no
	// parent_chunk_id column to walk; IncludeParent is a no-op.
	IncludeParent bool

	// NeighborWindow includes up to N sibling chunks on each side of the
	// requested chunk, ordered by chunk_index. Two chunks are siblings
	// when they share the same parent_chunk_id (NULL counts as a single
	// sibling group), so for a leaf the neighborhood stays inside the
	// same parent span and for a flat or parent chunk the neighborhood
	// is other top-level chunks under the same record. Zero means no
	// neighbors are included; the requested chunk is still returned by
	// itself.
	//
	// Against snapshots built before schema v5 (#16), the parent grouping
	// is unavailable, so neighbors degrade to "other chunks in the same
	// record_ref with chunk_index in the requested window."
	NeighborWindow int
}

type FusionStrategy interface {
	Fuse(arms []RetrievalArm, limit int) ([]SearchHit, error)
}

type HitProvenance struct {
	Arms map[string]ArmEvidence
}

type IntegrityMode int

type LexicalSearchParams struct {
	// Text is the free-form query text. Empty rejects with a
	// "search text is required" error.
	Text string
	// Limit caps the number of SearchHits returned. Zero or negative
	// selects DefaultSearchLimit (10). Values above MaxSearchLimit
	// reject with an error instead of being silently capped.
	Limit int
	// Kinds filters candidate records to the supplied kind list. Nil
	// or empty means "no filter, all kinds".
	Kinds []string
	// Refs filters candidate records to the supplied record refs. Nil
	// or empty means "no filter, all refs".
	Refs []string
	// Metadata filters candidate records by stored record metadata. Semantics
	// match SearchParams.Metadata.
	Metadata MetadataFilter
	// OmitMetadata skips reading and decoding records.metadata_json for each
	// returned hit. Metadata filters still apply inside SQL.
	OmitMetadata bool
}

type LexicalSearchQuery struct {
	// Path is the OS-native filesystem path to the snapshot. On
	// Windows both forward and back slashes are accepted — the store
	// package normalizes drive prefixes on open.
	Path string
	LexicalSearchParams
}

type MetadataFilter map[string][]string

type OutlineQuery struct {
	// Refs filters candidate records to the supplied refs. Nil or empty
	// means "no filter, all refs".
	Refs []string
	// Kinds filters candidate records to the supplied kinds. Nil or empty
	// means "no filter, all kinds".
	Kinds []string
	// Metadata filters candidate records by stored record metadata. The
	// semantics match SearchParams.Metadata: keys are ANDed, values within
	// one key are ORed, and filters are evaluated in SQL without returning
	// the metadata payload.
	Metadata MetadataFilter
}

type OutlineRow struct {
	ChunkID       int64
	Ref           string
	Kind          string
	Title         string
	SourceRef     string
	Heading       string
	ParentChunkID *int64
	Depth         int
	ContextPrefix string
	SourceSpan    *chunk.SourceSpan
}

type RRFFusion struct {
	K                      int
	PreserveSingleArmScore bool
}

type RecordAggregationOptions struct {
	// Limit caps the number of records returned by AggregateSearchHitsByRecord
	// and SearchRecords. Zero or negative uses DefaultSearchLimit.
	Limit int

	// Strategy optionally overrides the default record aggregation strategy.
	// Nil uses DefaultRecordAggregation().
	Strategy RecordAggregationStrategy
}

type RecordAggregationStrategy interface {
	Aggregate(hits []SearchHit, opts RecordAggregationOptions) ([]RecordSearchHit, error)
}

type RecordHitContribution struct {
	ChunkID    int64
	Heading    string
	Score      float64
	SourceSpan *chunk.SourceSpan
	Provenance *HitProvenance
}

type RecordQuery struct {
	Refs  []string
	Kinds []string

	// OmitMetadata skips reading and decoding records.metadata_json for
	// each returned record. corpus.Record.Metadata stays nil instead of
	// being populated as a (possibly empty) map. Use this for bulk
	// exports/walks that only need ref/kind/title/body and never inspect
	// metadata; it skips the per-row json.Unmarshal call.
	OmitMetadata bool
}

type RecordSearchHit struct {
	Ref           string
	Kind          string
	Title         string
	SourceRef     string
	Metadata      map[string]string
	Score         float64
	Contributions []RecordHitContribution
}

type RecordSearchQuery struct {
	// Path is the OS-native filesystem path to the snapshot. On
	// Windows both forward and back slashes are accepted — the store
	// package normalizes drive prefixes on open.
	Path string
	SearchParams
	Aggregation RecordAggregationOptions
}

type RecordSource interface {
	Next(ctx context.Context) (corpus.Record, bool, error)
}

type RecordSourceFunc func(ctx context.Context) (corpus.Record, bool, error)

type Reranker interface {
	Rerank(ctx context.Context, query string, candidates []SearchHit) ([]SearchHit, error)
}

type RetrievalArm struct {
	Name      string
	Hits      []SearchHit
	Available bool
	Err       error
}

type ReuseStatus string

type SearchHit struct {
	ChunkID    int64
	Ref        string
	Kind       string
	Title      string
	SourceRef  string
	Heading    string
	Content    string
	SourceSpan *chunk.SourceSpan
	Metadata   map[string]string
	Score      float64
	// Provenance records which retrieval arms contributed to this hit.
	// It is populated by FusionStrategy implementations; non-fusion paths
	// (SearchVector, direct searchFTS callers) leave it nil.
	Provenance *HitProvenance
}

type SearchParams struct {
	// Text is the free-form query text. Empty rejects with a
	// "search text is required" error — this field has no default.
	Text string
	// Limit caps the number of SearchHits returned. Zero or negative
	// selects DefaultSearchLimit (10). Values above MaxSearchLimit
	// reject with an error instead of being silently capped.
	Limit int
	// Kinds filters candidate records to the supplied kind list. Nil
	// or empty means "no filter, all kinds".
	Kinds []string
	// Refs filters candidate records to the supplied record refs. Nil
	// or empty means "no filter, all refs". The filter is applied inside
	// each retrieval arm before that arm ranks and truncates candidates.
	Refs []string
	// Metadata filters candidate records by stored record metadata. Each
	// map key is matched exactly against corpus.Record.Metadata, values
	// are ORed within a key, and multiple keys are ANDed together. Empty
	// keys, empty value lists, and whitespace-only values reject; empty
	// metadata values are valid exact matches. The filter is applied inside
	// each retrieval arm before that arm ranks and truncates candidates.
	Metadata MetadataFilter
	// Embedder produces the query vector(s) used by the dense arm.
	// Nil rejects with a "search embedder is required" error — this
	// field has no default.
	Embedder embed.Embedder
	// Fusion optionally overrides the hybrid fusion strategy. Nil
	// uses DefaultFusion().
	Fusion FusionStrategy
	// Reranker optionally refines the candidate shortlist after
	// fusion. Nil skips reranking.
	Reranker Reranker

	// SearchDimension optionally runs a truncated-prefix vector prefilter
	// at this dimension, then rescores the shortlist with full-dim cosine.
	// Zero (default) uses the full stored dimension throughout. Positive
	// values must be <= the stored embedder dimension. Only valid when the
	// stored quantization is float32; returns an error against int8 indexes.
	// This is the shape Matryoshka Representation Learning (MRL) embeddings
	// rely on — callers who use non-MRL embeddings should leave it zero.
	//
	// The truncated path is a brute-force scan over chunks_vec, not a
	// vec0 kNN MATCH, so it is not asymptotically cheaper than the default
	// path: its win is constant-factor (fewer floats per cosine) and only
	// pays off when the truncated prefix preserves ranking. Treat this as
	// a tuning knob for MRL snapshots rather than a blanket speedup.
	SearchDimension int

	// OmitMetadata skips reading and decoding records.metadata_json for
	// each returned hit. SearchHit.Metadata stays nil instead of being
	// populated as a (possibly empty) map. This is an additive opt-out
	// for callers that drive ranking off Ref/Title/Content and never
	// inspect Metadata: it skips the per-hit json.Unmarshal and avoids
	// transferring the JSON blob from SQLite. Metadata filters
	// (SearchParams.Metadata) still work because they are evaluated
	// inside the SQL plan, not on the returned hit's payload.
	OmitMetadata bool
}

type SearchQuery struct {
	// Path is the OS-native filesystem path to the snapshot. On
	// Windows both forward and back slashes are accepted — the store
	// package normalizes drive prefixes on open.
	Path string
	SearchParams
}

type Section struct {
	ChunkID       int64
	Ref           string
	Kind          string
	Title         string
	SourceRef     string
	Heading       string
	Content       string
	ContextPrefix string
	SourceSpan    *chunk.SourceSpan
	Metadata      map[string]string
	Embedding     []float64
}

type SectionQuery struct {
	Refs  []string
	Kinds []string

	// IncludeEmbeddings asks Sections() and WalkSections() to populate
	// Section.Embedding from the stored vector column. Snapshots produced
	// by hierarchical policies (e.g., chunk.LateChunkPolicy) hold parent
	// rows that are storage-only context with no vector — those rows are
	// filtered out of an IncludeEmbeddings = true query because the
	// underlying chunks → chunks_vec join is inner. Set IncludeEmbeddings
	// = false to receive every chunk row (parents + leaves) without
	// embeddings.
	IncludeEmbeddings bool

	// OmitMetadata skips reading and decoding records.metadata_json for
	// each returned section. Section.Metadata stays nil instead of being
	// populated as a (possibly empty) map. Use this for embedding-heavy
	// section walks that do not consult per-record metadata.
	OmitMetadata bool
}

type Snapshot struct {
	// contains filtered or unexported fields
}

type SnapshotLexicalSearchQuery struct {
	LexicalSearchParams
}

type SnapshotRecordSearchQuery struct {
	SearchParams
	Aggregation RecordAggregationOptions
}

type SnapshotSearchQuery struct {
	SearchParams
}

type Stats struct {
	Path                string
	RecordCount         int
	ChunkCount          int
	KindCounts          map[string]int
	SchemaVersion       string
	EmbedderDimension   int
	EmbedderFingerprint string
	ContentFingerprint  string
	CreatedAt           string
}

type SumScoreRecordAggregation struct{}

type UpdateOptions struct {
	// Path is the OS-native filesystem path to the existing snapshot
	// to update in place. On Windows both forward and back slashes are
	// accepted — the store package normalizes drive prefixes on open.
	Path     string
	Embedder embed.Embedder

	// Contextualizer optionally produces a per-chunk prefix string. See
	// BuildOptions.Contextualizer for the contract. Leaving it nil
	// preserves the non-contextual path and produces chunks with an
	// empty persisted prefix.
	Contextualizer ChunkContextualizer

	// MaxChunkTokens sets the approximate maximum number of tokens (words)
	// per chunk. It should match the chunking policy used to build the current
	// index if callers want incremental updates to remain section-compatible.
	MaxChunkTokens int

	// ChunkOverlapTokens sets the approximate number of overlapping tokens
	// between adjacent sub-sections when a section is split. It should match
	// the chunking policy used to build the current index.
	ChunkOverlapTokens int

	// MaxChunkSections mirrors BuildOptions.MaxChunkSections for the
	// incremental-update path. Zero → DefaultMaxChunkSections; negative
	// → no cap.
	MaxChunkSections int

	// MaxPlannedRecords caps how many added/replaced records Update will
	// chunk, reuse-plan, and embed before opening its write transaction.
	// This bounds resident pre-transaction plan memory for callers that
	// split large ingests into repeated Update calls. Zero keeps the
	// historical unbounded behavior; negative values reject. The cap
	// applies only to added/replaced records, not removals.
	MaxPlannedRecords int

	// AllowSourceRemovals permits UpdateFromSource to remove stored records
	// that are absent from the supplied source. The default is false because
	// callers often think of "update from source" as a partial changed-record
	// feed. Use SyncFromSource for the full desired-corpus synchronization
	// path where removals are expected.
	AllowSourceRemovals bool

	// Quantization, when provided, must match the existing index — see
	// the store.Quantization* constants (float32, int8, binary) for the
	// accept-listed values. Leaving it empty reuses the stored
	// quantization metadata.
	Quantization string

	// ChunkPolicy mirrors BuildOptions.ChunkPolicy for the incremental
	// update path. Nil defaults to chunk.MarkdownPolicy with the
	// MaxChunkTokens / ChunkOverlapTokens / MaxChunkSections knobs
	// resolved here. The substrate does not enforce that the policy
	// matches the one used to build the snapshot — callers who switch
	// policies between Build and Update should expect reuse cache
	// misses on the affected sections (the leaves still re-embed
	// correctly; the snapshot just won't share embeddings across
	// rebuilds).
	ChunkPolicy chunk.Policy

	// IntegrityMode selects post-commit validation depth (#107). The
	// zero value, IntegrityModeFast, skips the SQLite-level whole-DB
	// PRAGMA passes so a small Update against a large snapshot no
	// longer pays for an O(database size) integrity_check on every
	// commit. IntegrityModeFull adds those passes back for callers that
	// want deep validation at the cost of full-corpus scans.
	IntegrityMode IntegrityMode
}

type UpdateResult struct {
	Path                 string
	UpsertedCount        int
	RemovedCount         int
	RecordCount          int
	ChunkCount           int
	UnchangedRecordCount int
	UnchangedChunkCount  int
	ReusedRecordCount    int
	ReusedChunkCount     int
	EmbeddedChunkCount   int
	EmbedderDimension    int
	EmbedderFingerprint  string
	ContentFingerprint   string
}

type VectorSearchQuery struct {
	// Embedding is the precomputed query vector. Empty rejects with
	// a "search embedding is required" error — this field has no
	// default.
	Embedding []float64
	// Limit caps the number of SearchHits returned. Zero or negative
	// selects DefaultSearchLimit (10). Values above MaxSearchLimit
	// reject with an error instead of being silently capped.
	Limit int
	// Kinds filters candidate records to the supplied kind list. Nil
	// or empty means "no filter, all kinds".
	Kinds []string
	// Refs filters candidate records to the supplied record refs. Nil
	// or empty means "no filter, all refs". The filter is applied before
	// the vector arm ranks and truncates candidates.
	Refs []string
	// Metadata filters candidate records by stored record metadata. Each
	// key is ANDed with the others; values within one key are ORed. Empty
	// keys, empty value lists, and whitespace-only values reject; empty
	// metadata values are valid exact matches. The filter is applied before
	// the vector arm ranks and truncates candidates.
	Metadata MetadataFilter

	// OmitMetadata skips reading and decoding records.metadata_json for
	// each returned hit. See SearchParams.OmitMetadata for the same
	// opt-out shape and rationale.
	OmitMetadata bool
}