uqa_storage/inverted_index/

contract.rs

//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

use super::IndexedFieldMetadata;
use super::{
    Analyzer, Arc, BTreeMap, BlockMaxScorer, DocId, FieldName, IndexStats, PostingEntry,
    PostingList, StorageBackendError, StorageBackendResult,
};
use crate::clustered_postings::BudgetedPostingReadCursor;
use crate::clustered_postings::{
    MaterializedPostingCursor, OccurrencePosting, PostingCursor, PostingScore,
};
use crate::read_control::StorageReadControl;
use crate::TokenTermKey;
use uqa_core::memory::Budgeted;
use uqa_core::TokenOccurrence;

/// Which side of the index/search pipeline a field analyzer applies to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AnalyzerPhase {
    /// Run only when *adding* documents.
    Index,
    /// Run only when *querying* documents (e.g. through `TermOperator`).
    Search,
    /// Run on both phases (the default).
    Both,
}

impl AnalyzerPhase {
    pub fn parse(s: &str) -> Result<Self, String> {
        match s {
            "index" => Ok(AnalyzerPhase::Index),
            "search" | "query" => Ok(AnalyzerPhase::Search),
            "both" => Ok(AnalyzerPhase::Both),
            _ => Err(format!("phase must be 'index'|'search'|'both', got `{s}`")),
        }
    }
}

impl std::str::FromStr for AnalyzerPhase {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::parse(s)
    }
}

pub trait InvertedIndex: Send + Sync {
    /// Whether persisted positional data must be rebuilt from original sources before this index can be read or mutated. The owning engine performs this after restoring exact analyzer revisions, in the same initial-open transaction.
    fn source_rebuild_required(&self) -> StorageBackendResult<bool> {
        Ok(false)
    }

    fn analyzer(&self) -> &Analyzer;

    /// Retain the exact default configuration, resource provider and already resolved revision without forcing deferred compilation. Controlled reconstruction requires this capability instead of copying and recompiling diagnostic configuration.
    fn default_analyzer_binding(&self) -> StorageBackendResult<super::AnalyzerDefault> {
        Err(StorageBackendError::Other(
            "retained default analyzer bindings are not supported by this backend".into(),
        ))
    }

    fn add_document(
        &mut self,
        doc_id: DocId,
        fields: BTreeMap<FieldName, String>,
    ) -> StorageBackendResult<()>;

    fn try_add_document(
        &mut self,
        doc_id: DocId,
        fields: BTreeMap<FieldName, String>,
    ) -> StorageBackendResult<()> {
        self.add_document(doc_id, fields)
    }

    /// Add or replace several documents in input order. The default preserves the point-mutation contract for custom backends; transactional persistent backends can override this to make the call atomic and coalesce writes that share physical posting clusters.
    fn try_add_documents(
        &mut self,
        documents: Vec<(DocId, BTreeMap<FieldName, String>)>,
    ) -> StorageBackendResult<()> {
        for (doc_id, fields) in documents {
            self.try_add_document(doc_id, fields)?;
        }
        Ok(())
    }

    /// Capture logical changes from the same analysis and original reverse entries used by the atomic replacement. The visitor must not reenter this provider. A transaction owner discards captured changes on error and registers successful intents before completing its statement; private writes and intents must share savepoint undo.
    fn try_add_documents_observed(
        &mut self,
        _documents: Vec<(DocId, BTreeMap<FieldName, String>)>,
        _visit: &mut super::InvertedIndexChangeVisitor<'_>,
    ) -> StorageBackendResult<()> {
        Err(StorageBackendError::Other(
            "evaluated text mutation observations are not supported by this backend".into(),
        ))
    }

    /// Deletion captures the original analyzed terms without reconstructing the document or rerunning its analyzer. An absent document produces no logical change.
    fn try_remove_document_observed(
        &mut self,
        doc_id: DocId,
        visit: &mut super::InvertedIndexChangeVisitor<'_>,
    ) -> StorageBackendResult<()> {
        self.try_add_documents_observed(vec![(doc_id, BTreeMap::new())], visit)
    }

    fn remove_document(&mut self, doc_id: DocId) -> StorageBackendResult<()>;

    fn try_remove_document(&mut self, doc_id: DocId) -> StorageBackendResult<()> {
        self.remove_document(doc_id)
    }

    fn clear(&mut self) -> StorageBackendResult<()>;

    fn try_clear(&mut self) -> StorageBackendResult<()> {
        self.clear()
    }

    fn try_rebuild_documents(
        &mut self,
        documents: Vec<(DocId, BTreeMap<FieldName, String>)>,
    ) -> StorageBackendResult<()> {
        self.try_clear()?;
        for (doc_id, fields) in documents {
            if !fields.is_empty() {
                self.try_add_document(doc_id, fields)?;
            }
        }
        Ok(())
    }

    fn get_posting_list(&self, field: &str, term: &str) -> StorageBackendResult<PostingList>;

    /// Unique-position compatibility projection for an exact term key. Legacy providers accept scalar keys and reject unpaired UTF-16 explicitly.
    fn get_posting_list_key(
        &self,
        field: &str,
        term: &TokenTermKey,
    ) -> StorageBackendResult<PostingList> {
        self.get_posting_list(field, &term.to_term().into_string()?)
    }

    /// Score cursor with exact term identity and occurrence frequency independent of unique positions.
    fn posting_cursor_key(
        &self,
        field: &str,
        term: &TokenTermKey,
    ) -> StorageBackendResult<Box<dyn PostingCursor>> {
        self.posting_cursor(field, &term.to_term().into_string()?)
    }

    /// Traverse candidates while retaining this index read. Providers with borrowed posting maps can avoid copying the entire term support; owned persistent cursors keep their incremental reads.
    fn posting_read_cursor_key<'a>(
        &'a self,
        field: &'a str,
        term: &TokenTermKey,
    ) -> StorageBackendResult<Box<dyn crate::clustered_postings::PostingReadCursor + 'a>> {
        Ok(Box::new(crate::clustered_postings::OwnedPostingReadCursor(
            self.posting_cursor_key(field, term)?,
        )))
    }

    /// Open a cursor that owns every query allocation under the supplied allowance. Providers must implement this capability without an unbounded materialization fallback.
    fn posting_read_cursor_key_budgeted<'a>(
        &'a self,
        field: &'a str,
        term: &'a TokenTermKey,
        control: &StorageReadControl,
    ) -> StorageBackendResult<BudgetedPostingReadCursor<'a>> {
        crate::clustered_postings::open_controlled_cursor(self, field, term, control)
    }

    /// Visit encoded score clusters in ascending order under the retained provider read. Temporary payloads must be reserved before fetching; callbacks must not reenter the provider.
    fn visit_score_clusters(
        &self,
        _field: &str,
        _term: &TokenTermKey,
        _after: Option<u64>,
        _limit: usize,
        control: &StorageReadControl,
        _visit: &mut crate::clustered_postings::ScoreClusterVisitor<'_>,
    ) -> StorageBackendResult<()> {
        control.check()?;
        Err(StorageBackendError::Other(
            "controlled score cluster reads are not supported by this backend".into(),
        ))
    }

    /// Decode one document's exact occurrences with provider-owned input and output reservations and cancellation checks.
    fn get_occurrences_budgeted(
        &self,
        _doc_id: DocId,
        _field: &str,
        _term: &TokenTermKey,
        control: &StorageReadControl,
    ) -> StorageBackendResult<Budgeted<Vec<TokenOccurrence>>> {
        control.check()?;
        Err(StorageBackendError::Other(
            "controlled occurrence reads are not supported by this backend".into(),
        ))
    }

    /// Complete graph edges in document order, preserving occurrence multiplicity and original source coordinates. Legacy positions cannot implement this contract without a source rebuild.
    fn get_occurrence_postings(
        &self,
        _field: &str,
        _term: &TokenTermKey,
    ) -> StorageBackendResult<Vec<OccurrencePosting>> {
        Err(StorageBackendError::Other(
            "lossless occurrence storage is not supported by this backend".into(),
        ))
    }

    /// Exact occurrences for one document and term; an absent document or term has no occurrences.
    fn get_occurrences(
        &self,
        doc_id: DocId,
        field: &str,
        term: &TokenTermKey,
    ) -> StorageBackendResult<Vec<TokenOccurrence>> {
        Ok(self
            .get_occurrence_postings(field, term)?
            .into_iter()
            .find(|posting| posting.doc_id == doc_id)
            .map_or_else(Vec::new, |posting| posting.occurrences))
    }

    /// Original stream-end state and revision metadata published with a document field, including fields that emitted no tokens.
    fn indexed_field_metadata(
        &self,
        _doc_id: DocId,
        _field: &str,
    ) -> StorageBackendResult<Option<IndexedFieldMetadata>> {
        Err(StorageBackendError::Other(
            "indexed field analysis metadata is not supported by this backend".into(),
        ))
    }

    fn doc_freq_key(&self, field: &str, term: &TokenTermKey) -> StorageBackendResult<u64> {
        self.doc_freq(field, &term.to_term().into_string()?)
    }

    fn get_term_freq_key(
        &self,
        doc_id: DocId,
        field: &str,
        term: &TokenTermKey,
    ) -> StorageBackendResult<u64> {
        self.get_term_freq(doc_id, field, &term.to_term().into_string()?)
    }

    /// Sorted canonical term keys, including unpaired units. String-only vocabulary APIs must return an error if projection would lose identity.
    fn vocabulary_keys(&self, field: &str) -> StorageBackendResult<Vec<TokenTermKey>> {
        Ok(self
            .vocabulary_terms(field)?
            .iter()
            .map(|term| TokenTermKey::from_text(term))
            .collect())
    }

    fn get_posting_lists_bulk(
        &self,
        field: &str,
        terms: &[String],
    ) -> StorageBackendResult<Vec<PostingList>> {
        terms
            .iter()
            .map(|term| self.get_posting_list(field, term))
            .collect()
    }

    /// Open a doc-id ordered score cursor for one term.
    ///
    /// The cursor carries term frequency and document length directly so
    /// ranking does not need positional payloads or per-document length
    /// lookups. Persistent backends override this with lazy clustered
    /// cursors; the default preserves compatibility for custom backends.
    fn posting_cursor(
        &self,
        field: &str,
        term: &str,
    ) -> StorageBackendResult<Box<dyn PostingCursor>> {
        let posting_list = self.get_posting_list(field, term)?;
        let mut entries = Vec::with_capacity(posting_list.len());
        for posting in posting_list {
            let term_freq = self.get_term_freq(posting.doc_id, field, term)?;
            entries.push(PostingScore {
                doc_id: posting.doc_id,
                term_freq,
                doc_length: self.get_doc_length(posting.doc_id, field)?,
            });
        }
        Ok(Box::new(MaterializedPostingCursor::new(entries)?))
    }

    fn posting_cursors_bulk(
        &self,
        field: &str,
        terms: &[String],
    ) -> StorageBackendResult<Vec<Box<dyn PostingCursor>>> {
        terms
            .iter()
            .map(|term| self.posting_cursor(field, term))
            .collect()
    }

    /// Open exact-key cursors in input order, retaining repeated query terms. Scalar custom backends retain their optimized bulk implementation.
    fn posting_cursors_keys_bulk(
        &self,
        field: &str,
        terms: &[TokenTermKey],
    ) -> StorageBackendResult<Vec<Box<dyn PostingCursor>>> {
        if let Some(scalar) = terms
            .iter()
            .map(|key| key.as_str().map(str::to_owned))
            .collect::<Option<Vec<_>>>()
        {
            return self.posting_cursors_bulk(field, &scalar);
        }
        terms
            .iter()
            .map(|term| self.posting_cursor_key(field, term))
            .collect()
    }

    /// Read exact-key support without projecting UTF-16 term identity.
    fn get_posting_lists_keys_bulk(
        &self,
        field: &str,
        terms: &[TokenTermKey],
    ) -> StorageBackendResult<Vec<PostingList>> {
        if let Some(scalar) = terms
            .iter()
            .map(|key| key.as_str().map(str::to_owned))
            .collect::<Option<Vec<_>>>()
        {
            return self.get_posting_lists_bulk(field, &scalar);
        }
        terms
            .iter()
            .map(|term| self.get_posting_list_key(field, term))
            .collect()
    }

    /// Load exact-key scorer-versioned bounds. Custom scalar providers expose no raw-key materialization by default.
    fn persisted_block_max_scores_keys_bulk(
        &self,
        field: &str,
        terms: &[TokenTermKey],
        scorer_fingerprint: &str,
    ) -> StorageBackendResult<Vec<Option<Vec<f64>>>> {
        if let Some(scalar) = terms
            .iter()
            .map(|key| key.as_str().map(str::to_owned))
            .collect::<Option<Vec<_>>>()
        {
            return self.persisted_block_max_scores_bulk(field, &scalar, scorer_fingerprint);
        }
        terms
            .iter()
            .map(|key| match key.as_str() {
                Some(term) => self.persisted_block_max_scores(field, term, scorer_fingerprint),
                None => Ok(None),
            })
            .collect()
    }

    /// Exact-key scoring inputs aligned with both the document and query-term arrays, including repetitions.
    fn get_scoring_inputs_keys_bulk(
        &self,
        doc_ids: &[DocId],
        field: &str,
        terms: &[TokenTermKey],
    ) -> StorageBackendResult<Vec<(u64, Vec<u64>)>> {
        if let Some(scalar) = terms
            .iter()
            .map(|key| key.as_str().map(str::to_owned))
            .collect::<Option<Vec<_>>>()
        {
            return self.get_scoring_inputs_bulk(doc_ids, field, &scalar);
        }
        doc_ids
            .iter()
            .map(|id| {
                Ok((
                    self.get_doc_length(*id, field)?,
                    terms
                        .iter()
                        .map(|key| self.get_term_freq_key(*id, field, key))
                        .collect::<StorageBackendResult<_>>()?,
                ))
            })
            .collect()
    }

    /// Persist scorer-specific block maxima for every term in `field`.
    ///
    /// Backends that do not provide durable auxiliary indexes return `false`.
    /// The fingerprint must include every scorer and corpus statistic that can
    /// affect a term contribution; reads only expose rows with an exact match.
    fn rebuild_persisted_block_max(
        &mut self,
        _field: &str,
        _scorer: &dyn BlockMaxScorer,
        _scorer_fingerprint: &str,
    ) -> StorageBackendResult<bool> {
        Ok(false)
    }

    /// Load scorer-versioned block maxima for one posting list. `None` means
    /// the backend has no complete, valid materialization for this scorer.
    fn persisted_block_max_scores(
        &self,
        _field: &str,
        _term: &str,
        _scorer_fingerprint: &str,
    ) -> StorageBackendResult<Option<Vec<f64>>> {
        Ok(None)
    }

    /// Load scorer-versioned block maxima for several terms while preserving input order; persistent backends override this to avoid one storage round trip per term.
    fn persisted_block_max_scores_bulk(
        &self,
        field: &str,
        terms: &[String],
        scorer_fingerprint: &str,
    ) -> StorageBackendResult<Vec<Option<Vec<f64>>>> {
        terms
            .iter()
            .map(|term| self.persisted_block_max_scores(field, term, scorer_fingerprint))
            .collect()
    }

    /// Visit every legacy unique-position projection for `(field, term)` in ascending doc-id order without handing out an owned list.
    ///
    /// Occurrence-backed providers may materialize each entry during its callback. Frequency-only scoring should use [`InvertedIndex::for_each_term_freq`] to avoid building position buffers; graph consumers use the occurrence interfaces to preserve multiplicity.
    fn for_each_posting(
        &self,
        field: &str,
        term: &str,
        visit: &mut dyn FnMut(&PostingEntry),
    ) -> StorageBackendResult<()> {
        for entry in &self.get_posting_list(field, term)? {
            visit(entry);
        }
        Ok(())
    }

    /// Visit `(doc_id, term_frequency)` pairs without requiring callers to
    /// materialize or decode payload details they do not use. The default
    /// uses posting support and the authoritative frequency accessor;
    /// persistent backends can stream compact frequency projections.
    fn for_each_term_freq(
        &self,
        field: &str,
        term: &str,
        visit: &mut dyn FnMut(DocId, u64),
    ) -> StorageBackendResult<()> {
        for entry in &self.get_posting_list(field, term)? {
            visit(entry.doc_id, self.get_term_freq(entry.doc_id, field, term)?);
        }
        Ok(())
    }

    fn doc_freq(&self, field: &str, term: &str) -> StorageBackendResult<u64>;

    fn get_doc_length(&self, doc_id: DocId, field: &str) -> StorageBackendResult<u64>;

    fn get_term_freq(&self, doc_id: DocId, field: &str, term: &str) -> StorageBackendResult<u64>;

    fn doc_count(&self) -> StorageBackendResult<u64>;

    fn total_field_length(&self, field: &str) -> StorageBackendResult<u64>;

    /// Number of documents that have indexed content for `field`.
    fn field_doc_count(&self, field: &str) -> StorageBackendResult<u64> {
        self.doc_length_count(Some(field))
    }

    /// Field-specific statistics for BM25 scoring.
    ///
    /// BM25 length normalization and IDF collection size are defined for
    /// one field. Reusing table-wide totals mixes unrelated field lengths
    /// and produces scores that cannot match a field-scoped BM25 scorer.
    fn field_stats(&self, field: &str) -> StorageBackendResult<IndexStats> {
        super::defaults::field_stats(self, field)
    }

    /// [`InvertedIndex::field_stats`] without the vocabulary-wide
    /// document-frequency map.
    ///
    /// Query execution that already knows its terms' document
    /// frequencies (it read them off the posting lists) only needs the
    /// field's document count and average length; copying the whole
    /// term dictionary per query is O(vocabulary) for nothing.
    fn field_stats_scalar(&self, field: &str) -> StorageBackendResult<IndexStats> {
        super::defaults::field_stats_scalar(self, field)
    }

    /// Read only field scoring scalars with producer-owned temporary reservations.
    fn field_stats_scalar_budgeted(
        &self,
        _field: &str,
        control: &StorageReadControl,
    ) -> StorageBackendResult<IndexStats> {
        control.check()?;
        Err(StorageBackendError::Other(
            "controlled field statistics are not supported by this backend".into(),
        ))
    }

    /// Sorted unique indexed terms for `field`.
    ///
    /// Backends implement this from their term dictionary rather than by
    /// re-analyzing stored documents. This is the source used by Bayesian
    /// calibration reservoir sampling.
    fn vocabulary_terms(&self, _field: &str) -> StorageBackendResult<Vec<String>> {
        Ok(Vec::new())
    }

    /// Fully-populated [`IndexStats`] snapshot for the cost model and
    /// scoring layer. Implementations may cache this between mutations.
    fn stats(&self) -> StorageBackendResult<IndexStats>;

    /// Number of posting rows. With `field = Some(..)`, limits the count
    /// to one indexed field.
    fn posting_count(&self, _field: Option<&str>) -> StorageBackendResult<u64> {
        Ok(0)
    }

    /// Number of `(doc_id, field)` length rows. With `field = Some(..)`,
    /// this is the number of documents indexed for that field.
    fn doc_length_count(&self, _field: Option<&str>) -> StorageBackendResult<u64> {
        Ok(0)
    }

    /// Number of distinct indexed terms. With `field = Some(..)`, limits
    /// the count to one indexed field.
    fn term_count(&self, _field: Option<&str>) -> StorageBackendResult<u64> {
        Ok(0)
    }

    /// Read-only handle suitable for an `ExecutionContext`.
    fn snapshot(&self) -> StorageBackendResult<Arc<dyn InvertedIndex>>;

    /// Capture the selected view with its caller's retention allowance. Providers that already retain their own read boundary preserve it; memory owners override this hook to charge their shared state before publication.
    fn snapshot_with_control(
        &self,
        control: &crate::read_control::StorageReadControl,
    ) -> StorageBackendResult<Arc<dyn InvertedIndex>> {
        control.check()?;
        let snapshot = self.snapshot()?;
        control.check()?;
        Ok(snapshot)
    }

    /// Independent writable copy used to restore an in-memory engine
    /// transaction without reconstructing analyzer state from documents.
    fn writable_snapshot(&self) -> StorageBackendResult<Box<dyn InvertedIndex>> {
        Err(StorageBackendError::Other(
            "writable inverted-index snapshots are not supported by this backend".into(),
        ))
    }

    // -- Extended inverted-index surface ---

    /// Names of every field with at least one indexed document.
    /// Default implementation walks the [`IndexStats`] snapshot's
    /// total-length map. Backends with a richer schema can override.
    fn field_names(&self) -> StorageBackendResult<Vec<FieldName>> {
        Ok(Vec::new())
    }

    /// Posting list for `term` across every indexed field, unioned
    /// together. Default implementation sums per-field posting lists
    /// via [`PostingList::merge_union`].
    fn get_posting_list_any_field(&self, term: &str) -> StorageBackendResult<PostingList> {
        super::defaults::get_posting_list_any_field(self, term)
    }

    /// Document frequency of `term` across every indexed field.
    fn doc_freq_any_field(&self, term: &str) -> StorageBackendResult<u64> {
        super::defaults::doc_freq_any_field(self, term)
    }

    /// Sum of all per-field token lengths for a single doc.
    fn get_total_doc_length(&self, doc_id: DocId) -> StorageBackendResult<u64> {
        super::defaults::get_total_doc_length(self, doc_id)
    }

    /// Bulk doc-length lookup. Default falls back to per-id calls.
    fn get_doc_lengths_bulk(
        &self,
        doc_ids: &[DocId],
        field: &str,
    ) -> StorageBackendResult<BTreeMap<DocId, u64>> {
        let mut out = BTreeMap::new();
        for doc_id in doc_ids {
            out.insert(*doc_id, self.get_doc_length(*doc_id, field)?);
        }
        Ok(out)
    }

    /// Bulk term-frequency lookup. Default falls back to per-id calls.
    fn get_term_freqs_bulk(
        &self,
        doc_ids: &[DocId],
        field: &str,
        term: &str,
    ) -> StorageBackendResult<BTreeMap<DocId, u64>> {
        super::defaults::get_term_freqs_bulk(self, doc_ids, field, term)
    }

    /// Fetch the document length and one term frequency per query term for
    /// every requested document. Results stay aligned with `doc_ids`.
    /// Persistent backends override this to collapse the scoring loop's
    /// per-document point reads into a small number of set-oriented queries.
    fn get_scoring_inputs_bulk(
        &self,
        doc_ids: &[DocId],
        field: &str,
        terms: &[String],
    ) -> StorageBackendResult<Vec<(u64, Vec<u64>)>> {
        let mut out = Vec::with_capacity(doc_ids.len());
        for doc_id in doc_ids {
            let mut term_freqs = Vec::with_capacity(terms.len());
            for term in terms {
                term_freqs.push(self.get_term_freq(*doc_id, field, term)?);
            }
            out.push((self.get_doc_length(*doc_id, field)?, term_freqs));
        }
        Ok(out)
    }

    /// Total term frequency for a doc summed across every indexed
    /// field.
    fn get_total_term_freq(&self, doc_id: DocId, term: &str) -> StorageBackendResult<u64> {
        super::defaults::get_total_term_freq(self, doc_id, term)
    }

    /// Bind an analyzer to a single field for the given phase.
    /// `Both` writes to both the index-side and search-side maps; the
    /// default impl errors so backends that don't support per-field
    /// analyzers fail loud rather than silently dropping the request.
    fn set_field_analyzer(
        &mut self,
        _field: &str,
        _analyzer: Analyzer,
        _phase: AnalyzerPhase,
    ) -> Result<(), String> {
        Err("set_field_analyzer not supported by this InvertedIndex backend".into())
    }

    /// Remove every per-field analyzer override for `field`.  This is the
    /// inverse of `set_field_analyzer(..., Both)` and is required when the
    /// final logical FTS index for a field is dropped.  The default errors so
    /// a backend cannot silently retain stale analysis behavior.
    fn remove_field_analyzers(&mut self, _field: &str) -> Result<(), String> {
        Err("remove_field_analyzers not supported by this InvertedIndex backend".into())
    }

    /// Index-time analyzer for `field`; falls back to
    /// [`InvertedIndex::analyzer`] when no override is set.
    fn get_field_analyzer(&self, _field: &str) -> Analyzer {
        self.analyzer().clone()
    }

    /// Compatibility configuration for search. Built-in providers return their independent retained search revision's inputs; this default preserves the index fallback for custom legacy providers. Use `search_analyzer_revision` for execution with exact resource ownership.
    fn get_search_analyzer(&self, field: &str) -> Analyzer {
        self.get_field_analyzer(field)
    }

    /// Retain the exact executable index revision. Built-in providers resolve their default once and keep field revisions immutable.
    fn index_analyzer_revision(
        &self,
        field: &str,
    ) -> StorageBackendResult<Arc<uqa_analysis::CompiledAnalyzer>> {
        Ok(self.get_field_analyzer(field).compile()?)
    }

    /// Retain the exact executable search revision independently of subsequent index assignments.
    fn search_analyzer_revision(
        &self,
        field: &str,
    ) -> StorageBackendResult<Arc<uqa_analysis::CompiledAnalyzer>> {
        Ok(self.get_search_analyzer(field).compile()?)
    }

    /// Install a validated revision without reopening its resources. This does not rebuild existing documents; graph providers reject a different index revision on a populated field and require `rebuild_with_analyzer_revision` instead.
    fn set_field_analyzer_revision(
        &mut self,
        _field: &str,
        _revision: Arc<uqa_analysis::CompiledAnalyzer>,
        _phase: AnalyzerPhase,
    ) -> Result<(), String> {
        Err("immutable analyzer revisions are not supported by this backend".into())
    }

    /// Install a complete retained pair atomically. Failure changes neither side; this does not rebuild existing postings.
    fn set_field_analyzer_revisions(
        &mut self,
        _field: &str,
        _index: Arc<uqa_analysis::CompiledAnalyzer>,
        _search: Arc<uqa_analysis::CompiledAnalyzer>,
    ) -> Result<(), String> {
        Err("atomic analyzer revision pairs are not supported by this backend".into())
    }

    /// Replace the complete indexed document set and selected analyzer sides together. Failure retains the previous postings and bindings; providers must implement their own atomic publication.
    fn rebuild_with_analyzer_revision(
        &mut self,
        _field: &str,
        _revision: Arc<uqa_analysis::CompiledAnalyzer>,
        _phase: AnalyzerPhase,
        _documents: Vec<(DocId, BTreeMap<FieldName, String>)>,
    ) -> StorageBackendResult<()> {
        Err(StorageBackendError::Other(
            "atomic analyzer revision rebuild is not supported by this backend".into(),
        ))
    }

    /// Rebuild under the caller's cancellation token. Cancellation must retain the complete previous index; custom providers must implement atomic staging and cancellation.
    fn try_rebuild_documents_cancellable(
        &mut self,
        _documents: Vec<(DocId, BTreeMap<FieldName, String>)>,
        cancellation: &uqa_core::CancellationToken,
    ) -> StorageBackendResult<()> {
        cancellation.check()?;
        Err(StorageBackendError::Other(
            "cancellable atomic index rebuild is not supported by this backend".into(),
        ))
    }

    /// Replace postings and selected analyzer revisions together, retaining both on cancellation before publication.
    fn rebuild_with_analyzer_revision_cancellable(
        &mut self,
        _field: &str,
        _revision: Arc<uqa_analysis::CompiledAnalyzer>,
        _phase: AnalyzerPhase,
        _documents: Vec<(DocId, BTreeMap<FieldName, String>)>,
        cancellation: &uqa_core::CancellationToken,
    ) -> StorageBackendResult<()> {
        cancellation.check()?;
        Err(StorageBackendError::Other(
            "cancellable atomic analyzer revision rebuild is not supported by this backend".into(),
        ))
    }
}