Struct IndexPublicationGuard 

pub struct IndexPublicationGuard<'store> { /* private fields */ }

Exclusive parent-owned atomic publication over all derived projections.

Implementations

impl IndexPublicationGuard<'_>

pub fn replace_repository_graph_from_staging( &mut self, project: ProjectInstanceId, staging: &AtlasStore, control: Option<&IndexWorkControl>, ) -> DbResult<()>

Replace the complete graph from one typed disposable staging database.

Errors

Returns an error when staging integrity, project identity, generation, normalized constraints, cancellation, or SQLite copying fails.

pub fn replace_repository_graph( &mut self, project: ProjectInstanceId, entities: &[GraphEntity], relations: &[LogicalRelation], occurrences: &[RelationOccurrence], coverage: &[CoverageRecord], ) -> DbResult<()>

Replace the complete normalized repository graph inside this publication.

Errors

Returns an error when records do not belong to the pending generation or selected project, a stable-key collision is detected, or SQLite fails.

pub fn replace_repository_graph_with_resolution_keys( &mut self, project: ProjectInstanceId, entities: &[GraphEntity], relations: &[LogicalRelation], occurrences: &[RelationOccurrence], coverage: &[CoverageRecord], entity_exports: &[EntityResolutionKey], relation_dependencies: &[RelationDependencyKey], ) -> DbResult<()>

Replace the complete graph and canonical resolution-key projection atomically.

Errors

Returns an error when graph or key records do not belong to the pending generation and selected project, a stable-key collision is detected, an owner has no exact source path, or SQLite fails.

pub fn replace_repository_graph_for_paths( &mut self, project: ProjectInstanceId, affected_paths: &[String], entities: &[GraphEntity], relations: &[LogicalRelation], occurrences: &[RelationOccurrence], coverage: &[CoverageRecord], ) -> DbResult<()>

Replace the normalized graph closure owned by affected repository paths.

Unchanged rows stay physically untouched and are reconstructed at the next complete publication generation. The caller supplies the complete new closure for the affected paths.

Errors

Returns an error when records do not belong to the pending generation or selected project, a stable-key collision is detected, or SQLite fails.

pub fn replace_repository_graph_for_paths_with_resolution_keys( &mut self, project: ProjectInstanceId, affected_paths: &[String], entities: &[GraphEntity], relations: &[LogicalRelation], occurrences: &[RelationOccurrence], coverage: &[CoverageRecord], entity_exports: &[EntityResolutionKey], relation_dependencies: &[RelationDependencyKey], ) -> DbResult<()>

Replace one affected graph closure and its canonical resolution keys atomically.

Errors

Returns an error when graph or key records do not belong to the pending generation and selected project, a stable-key collision is detected, an owner has no exact source path, or SQLite fails.

impl IndexPublicationGuard<'_>

pub fn begin_scan_replacement(&mut self) -> DbResult<()>

Mark the current scan projection absent before bounded replacement batches.

The caller must finish with Self::finish_scan_replacement before completing this publication. Dropping the guard rolls every partial replacement batch back with the parent transaction.

Errors

Returns an error if the scan projection cannot be updated.

pub fn upsert_scan_node_batch(&mut self, nodes: &[Node]) -> DbResult<()>

Upsert one bounded scan-node batch inside the parent publication.

Errors

Returns an error if any node in the batch cannot be persisted.

pub fn finish_scan_replacement(&mut self) -> DbResult<()>

Remove derived projections for nodes left absent after replacement.

Errors

Returns an error if stale projections cannot be removed.

pub fn complete(self) -> DbResult<()>

Commit every derived projection and advance the complete generation exactly once.

Errors

Returns an error if generation metadata is invalid, a projection-only refresh no longer matches its established contract, or commit fails.

Methods from Deref<Target = AtlasStore>

pub fn export_derived_graph_snapshot(&self) -> DbResult<DerivedGraphSnapshot>

Build a portable graph snapshot from a private SQLite backup.

Errors

Returns an error for incomplete publications, corrupt or oversized captures, private temporary-file failures, or invalid graph rows.

pub fn import_derived_graph_snapshot( &mut self, snapshot: &DerivedGraphSnapshot, ) -> DbResult<DerivedGraphSnapshotImport>

Validate and atomically publish a portable graph into this project.

The destination must already have the same current source state and full capability contract. Only derived graph rows are replaced; destination identity, source projections, purposes, health state, settings, and telemetry stay owned by the destination database.

Errors

Returns an error before publication for incompatible source/capability state or malformed content. Publication conflicts and SQLite failures roll the existing generation back through the normal guard.

pub fn project_instance_id(&self) -> DbResult<Option<ProjectInstanceId>>

Return the durable project instance identity, when initialized.

Errors

Returns an error when the singleton row is malformed or cannot be read.

pub fn repository_navigation_connections( &self, owners: &[RepositoryNavigationNode], family_limit: u32, sample_limit: usize, ) -> DbResult<Vec<RepositoryNavigationConnections>>

Load bounded current graph context for folder and file navigation rows.

Owners are processed through a fixed-size set-oriented statement per chunk. Each family uses separate indexed outbound and inbound branches, exact file plus manifest ownership, or bounded folder-prefix ownership. No partial result is returned if any statement or row fails.

Errors

Returns an error for invalid paths or limits, unavailable publication state, SQLite failures, or any corrupt relation or endpoint row.

pub fn repository_graph_entity( &self, key: &GraphEntityKey, ) -> DbResult<Option<GraphEntity>>

Load one typed graph entity by its compact stable key.

Errors

Returns an error when publication state, project identity, row shape, canonical identity, or persisted key material is invalid.

pub fn repository_graph_entity_bounded( &self, key: &GraphEntityKey, generation: IndexGeneration, budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphReadBatch<GraphEntity>>

Load one optional exact entity under a stable graph read envelope.

Errors

Returns an error for a stale project or generation, cancellation, SQLite failure, corrupt entity state, or any decoded-byte, entity, or path hydration overrun. A missing exact key returns an empty successful batch with exact zero returned work.

pub fn repository_graph_entities_by_digest( &self, project: ProjectInstanceId, generation: IndexGeneration, digests: &[[u8; 32]], budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphReadBatch<GraphEntity>>

Hydrate an ordered unique set of graph entities from compact stable keys.

Errors

Returns an error for duplicate or oversized input, a stale project or generation, cancellation, a missing entity, SQLite failure, or any invalid persisted key or canonical identity. No partial set is returned.

pub fn repository_graph_entities_by_path( &self, project: ProjectInstanceId, path: &RepositoryNodePath, limit: u32, ) -> DbResult<RepositoryGraphPage<GraphEntity>>

Load a bounded page of entities that use one exact repository path.

Errors

Returns an error for invalid limits, unavailable publication state, project mismatch, SQLite failure, or any corrupt row in the page.

pub fn repository_graph_entities_by_path_bounded( &self, project: ProjectInstanceId, generation: IndexGeneration, path: &RepositoryNodePath, limit: u32, budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphReadPage<GraphEntity>>

Load one exact-path entity page under a stable graph read envelope.

Errors

Returns the same fail-closed errors as Self::repository_graph_entities_by_path, rejects a stale project or generation and any returned-row, decoded-byte, entity, or path hydration overrun, and meters the raw truncation sentinel.

pub fn repository_resolution_candidates( &self, key: &CanonicalResolutionKey, limit: u32, ) -> DbResult<RepositoryGraphPage<GraphEntity>>

Load bounded graph entities that export one exact canonical resolution key.

Errors

Returns an error for invalid limits, a project mismatch, a conflicting canonical witness, corrupt graph rows, or SQLite failure.

pub fn repository_resolution_candidates_for_keys( &self, project: ProjectInstanceId, keys: &[CanonicalResolutionKey], limit: u32, ) -> DbResult<RepositoryGraphPage<RepositoryResolutionCandidate>>

Load bounded export candidates for a canonical-key batch in one set-oriented pass.

Results retain the selecting key so callers can resolve several relation occurrences without issuing one query per dependency key. Duplicate input keys and duplicate candidate bindings are returned once in stable order.

Errors

Returns an error for invalid limits, mixed projects, a conflicting canonical witness, corrupt graph rows, or SQLite failure. A terminal row conversion failure rejects the complete operation rather than returning a partial candidate set.

pub fn repository_export_keys_for_paths( &self, project: ProjectInstanceId, paths: &[String], limit: u32, ) -> DbResult<RepositoryGraphPage<CanonicalResolutionKey>>

Load bounded canonical export keys previously owned by exact source paths.

The result is deduplicated and sorted by canonical key identity so callers can union it deterministically with newly staged exports.

Errors

Returns an error for invalid paths or limits, project mismatch, corrupt persisted keys, canonical witness collisions, or SQLite failure.

pub fn repository_affected_source_paths( &self, project: ProjectInstanceId, keys: &[CanonicalResolutionKey], limit: u32, ) -> DbResult<RepositoryGraphPage<RepositoryFilePath>>

Find the bounded distinct source paths that depend on canonical keys.

truncated is set from aggregate LIMIT + 1 handling. Callers must escalate to a full refresh before opening a publication transaction when it is true.

Errors

Returns an error for invalid limits, mixed projects, canonical witness collisions, invalid persisted paths, or SQLite failure. No mutation is performed.

pub fn repository_affected_source_footprint( &self, project: ProjectInstanceId, paths: &[String], limit: u32, ) -> DbResult<RepositoryAffectedSourceFootprint>

Account the persisted closure owned by exact affected source paths.

Resolution witnesses are conservatively counted once per retained export or dependency binding. Callers must require a full refresh when truncated is true; in that case rows is the limit + 1 lower bound and retained_bytes covers only that bounded prefix.

Errors

Returns an error for invalid paths or limits, corrupt persisted rows, unavailable owned indexes, or any SQLite preparation, iteration, or conversion failure. An unavailable graph returns an empty footprint; a differently bound graph returns the typed project-mismatch error.

pub fn repository_graph_relations( &self, query: RepositoryGraphRelationQuery, limit: u32, ) -> DbResult<RepositoryGraphPage<LogicalRelation>>

Load a bounded page of logical relations through one indexed query shape.

Errors

Returns an error for invalid limits, mismatched project identities, SQLite failure, or any corrupt entity/relation row in the complete page.

pub fn repository_graph_relation_rows( &self, query: RepositoryGraphRelationQuery, limit: u32, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphPage<RepositoryGraphRelationRow>>

Load a bounded relation page with unique endpoint hydration.

Errors

Returns an error for invalid limits, mismatched project identities, cancellation, SQLite failure, or any corrupt entity/relation row in the complete page.

pub fn repository_graph_relation_rows_by_digest( &self, project: ProjectInstanceId, generation: IndexGeneration, digests: &[[u8; 32]], budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphReadBatch<RepositoryGraphRelationRow>>

Hydrate an ordered unique set of normalized relations from compact stable keys.

Errors

Returns an error for duplicate or oversized input, a stale project or generation, cancellation, a missing relation or endpoint, SQLite failure, or any invalid persisted key or canonical identity. No partial set is returned.

pub fn repository_graph_adjacency_page( &self, frontier: &[GraphEntityKey], direction: RepositoryGraphDirection, continuation: Option<&RepositoryGraphAdjacencyContinuation>, limit: u32, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphAdjacencyPage>

Load one bounded direction-specific adjacency page for a unique frontier.

The complete frontier is bound through one statement whose indexed per-frontier branches each cap their candidate rows before the stable compound order. Endpoint entities are hydrated in bounded set-oriented batches. The opaque continuation is valid only with the same project, generation, frontier, and direction inside the same request snapshot.

Errors

Returns an error for invalid or mixed-project frontiers, invalid limits or continuation state, cancellation, SQLite failures, or any corrupt relation or endpoint row. No partial page is returned.

pub fn repository_graph_adjacency_page_bounded( &self, frontier: &[GraphEntityKey], direction: RepositoryGraphDirection, continuation: Option<&RepositoryGraphAdjacencyContinuation>, limit: u32, budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphAdjacencyReadPage>

Load one bounded adjacency page and report exact database work.

Errors

Returns the same fail-closed errors as Self::repository_graph_adjacency_page and rejects any page whose returned, decoded, endpoint, or path hydration crosses budget.

pub fn repository_graph_adjacency_page_filtered( &self, frontier: &[GraphEntityKey], direction: RepositoryGraphDirection, relation: Option<GraphRelationKind>, continuation: Option<&RepositoryGraphAdjacencyContinuation>, limit: u32, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphAdjacencyPage>

Load one bounded direction-specific adjacency page for an optional exact family.

Errors

Returns the same fail-closed errors as Self::repository_graph_adjacency_page and binds the optional family to continuation state.

pub fn repository_graph_adjacency_page_filtered_bounded( &self, frontier: &[GraphEntityKey], direction: RepositoryGraphDirection, relation: Option<GraphRelationKind>, continuation: Option<&RepositoryGraphAdjacencyContinuation>, limit: u32, budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphAdjacencyReadPage>

Load one family-filtered adjacency page and report exact database work.

Errors

Returns the same fail-closed errors as Self::repository_graph_adjacency_page_filtered and rejects any page whose complete query work crosses budget.

pub fn repository_graph_occurrences( &self, relation: &LogicalRelation, limit: u32, ) -> DbResult<RepositoryGraphPage<RelationOccurrence>>

Load bounded exact source occurrences for one logical relation.

Errors

Returns an error for invalid limits, project mismatch, unavailable publication state, SQLite failure, or any invalid span or key.

pub fn repository_graph_occurrence_pages( &self, relations: &[LogicalRelation], limit: u32, control: Option<&IndexWorkControl>, ) -> DbResult<Vec<RepositoryGraphPage<RelationOccurrence>>>

Load per-relation occurrence pages through one bounded set-oriented statement.

Result pages retain input order. Every generated branch uses the relation-leading unique index and admits only limit + 1 rows before the final stable merge.

Errors

Returns an error for mixed projects or generations, oversized input or intermediate work, cancellation, unavailable publication state, SQLite failure, or any invalid span or key.

pub fn repository_graph_occurrence_pages_bounded( &self, relations: &[LogicalRelation], limit: u32, budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphReadPages<RelationOccurrence>>

Load ordered per-relation occurrence pages under one exact read envelope.

Errors

Returns the same fail-closed errors as Self::repository_graph_occurrence_pages and rejects any aggregate returned-row, decoded-byte, or occurrence-path hydration overrun. Raw limit + 1 sentinels are included in decoded and path work.

pub fn repository_graph_coverage( &self, project: ProjectInstanceId, scope: &CoverageScope, limit: u32, ) -> DbResult<RepositoryGraphPage<CoverageRecord>>

Load bounded coverage rows for one exact project or path scope.

Errors

Returns an error for invalid limits, unavailable publication state, project mismatch, SQLite failure, or any inconsistent coverage row.

pub fn repository_graph_path_coverage( &self, project: ProjectInstanceId, paths: &[RepositoryNodePath], control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphPage<CoverageRecord>>

Load current coverage for a bounded unique set of exact repository paths.

The complete path set is bound to one prepared statement so service traversal never performs one coverage query per returned node.

Errors

Returns an error for duplicate or oversized path sets, cancellation, unavailable publication state, project mismatch, SQLite failure, or invalid persisted coverage.

pub fn repository_graph_path_coverage_bounded( &self, project: ProjectInstanceId, generation: IndexGeneration, paths: &[RepositoryNodePath], budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphReadPage<CoverageRecord>>

Load current exact-path coverage under one stable graph read envelope.

Errors

Returns the same fail-closed errors as Self::repository_graph_path_coverage, rejects a stale project or generation and any returned-row, decoded-byte, or coverage-path hydration overrun, and never returns a partial batch. The raw truncation sentinel is included in decoded and path work.

pub fn repository_coverage_page( &self, project: ProjectInstanceId, query: &RepositoryCoverageQuery, ) -> DbResult<RepositoryGraphPage<RepositoryCoverageRow>>

Discover one bounded page of current coverage with optional typed filters.

Errors

Returns an error for invalid bounds, unavailable publication state, project mismatch, SQLite failure, or invalid persisted coverage or parser provenance.

pub fn repository_graph_generation(&self) -> DbResult<Option<IndexGeneration>>

Return the complete generation used to reconstruct normalized graph rows.

Errors

Returns an error when publication metadata is incomplete or disagrees with the project identity’s active graph generation.

pub fn checkpoint_repository_graph_staging(&self) -> DbResult<()>

Checkpoint and truncate a completed disposable graph staging WAL.

Errors

Returns an error when another connection keeps the staging WAL busy or SQLite cannot complete the checkpoint.

pub fn begin_repository_graph_staging( &mut self, project: ProjectInstanceId, generation: IndexGeneration, ) -> DbResult<RepositoryGraphStagingGuard<'_>>

Begin one disposable typed repository-graph staging transaction.

Errors

Returns an error when the store belongs to another project, the generation is zero, or SQLite cannot begin or clear the staging transaction.

pub fn is_read_only(&self) -> bool

Return whether this store is restricted to non-mutating queries.

pub fn has_active_read_snapshot(&self) -> bool

Return whether this store currently owns an open read snapshot.

pub fn initialize_schema(&self) -> DbResult<()>

Validate, initialize, or migrate the schema through the storage owner.

Errors

Returns an error when schema compatibility, integrity, or migration fails.

pub fn replace_scan(&mut self, nodes: &[Node]) -> DbResult<()>

Upsert a full scan result and mark previously seen missing paths absent.

Errors

Returns an error if persistence fails.

pub fn upsert_scan_nodes(&mut self, nodes: &[Node]) -> DbResult<()>

Upsert a partial scan result without marking unrelated paths absent.

Errors

Returns an error if persistence fails.

pub fn mark_paths_absent(&mut self, paths: &[String]) -> DbResult<()>

Mark paths and their descendants absent after filesystem delete events.

Errors

Returns an error if persistence fails.

pub fn replace_file_texts_for_paths<'text>( &mut self, paths: &[String], texts: impl IntoIterator<Item = &'text IndexedFileText>, ) -> DbResult<()>

Replace indexed text for scanned file paths.

paths should contain every file path considered by the scan batch. Existing indexed text for those paths is cleared first so binary, deleted, or no-longer-UTF-8 files cannot leave stale searchable content.

Errors

Returns an error if persistence fails.

pub fn load_file_text(&self, path: &str) -> DbResult<Option<IndexedFileText>>

Load one indexed text row by repository path.

Errors

Returns an error if reading fails or stored counts are invalid.

pub fn query_file_text_fts_candidates( &self, query: &FileTextFtsQuery<'_>, control: Option<&IndexWorkControl>, ) -> DbResult<FileTextFtsPage>

Load a bounded FTS candidate superset for service-owned exact verification.

The request accepts only one safe ASCII-alphanumeric token. The MATCH expression is bound as data. Only authoritative metadata is returned; callers hydrate selected paths with Self::load_file_text after applying their file, byte, and time budgets.

Errors

Returns an error when the token shape or limit is unsafe, bounded work is canceled or reaches its deadline, or persisted rows are invalid.

pub fn visit_file_texts_for_fallback<A, V>( &self, path_prefix: Option<&str>, control: Option<&IndexWorkControl>, admit: A, visitor: V, ) -> DbResult<()>

where A: FnMut(&FileTextMetadata) -> DbResult<FileTextAdmission>, V: FnMut(IndexedFileText) -> DbResult<bool>,

Visit correctness-authoritative persisted text with predecode admission.

admit receives path and byte metadata before the source String is decoded from SQLite. Returning FileTextAdmission::Skip or FileTextAdmission::Stop therefore avoids allocating excluded source content. Returning false from visitor stops after an admitted row.

Errors

Returns an error when bounded work is canceled or reaches its deadline, persisted counts are invalid, or either callback returns an error.

pub fn file_text_fts_ready(&self) -> DbResult<bool>

Return whether the transactional FTS projection matches authoritative text.

This constant-work readiness check is suitable for the search hot path. Explicit settings diagnostics may additionally count projection rows.

Errors

Returns an error when durable revision metadata is malformed or partial.

pub fn file_text_fts_state(&self) -> DbResult<FileTextFtsState>

Report content-free FTS synchronization state for settings/readiness.

Errors

Returns an error when authoritative or projection row state cannot be inspected exactly.

pub fn load_file_texts_for_search( &self, literal_pattern: Option<&str>, case_sensitive: bool, ) -> DbResult<Vec<IndexedFileText>>

Load indexed text rows for search.

When literal_pattern is supplied, SQLite prefilters candidate files with a substring search before the service performs line-level matching. Regex and fuzzy searches pass None and still use the persisted text index instead of reopening source files from disk.

Errors

Returns an error if reading fails or stored counts are invalid.

pub fn visit_file_texts_for_search<F>( &self, literal_pattern: Option<&str>, case_sensitive: bool, visitor: F, ) -> DbResult<()>

where F: FnMut(IndexedFileText) -> DbResult<bool>,

Visit indexed text rows for search without materializing all rows.

When literal_pattern is supplied, SQLite prefilters candidate files with a substring search before the service performs line-level matching. Returning false from visitor stops iteration early.

Errors

Returns an error if reading fails, stored counts are invalid, or the visitor returns an error.

pub fn file_text_count(&self) -> DbResult<usize>

Count files with persisted UTF-8 text for indexed search.

Errors

Returns an error if reading fails.

pub fn file_text_byte_count(&self) -> DbResult<usize>

Sum persisted UTF-8 source bytes used by indexed search.

Errors

Returns an error if reading fails.

pub fn set_project_root(&mut self, root: &Path) -> DbResult<()>

Persist the canonical filesystem root for indexed repository files.

Errors

Returns an error if persistence fails.

pub fn project_root(&self) -> DbResult<Option<String>>

Load the canonical filesystem root for indexed repository files.

Errors

Returns an error if reading fails.

pub fn captured_project_binding(&self) -> DbResult<CapturedProjectBinding>

Return the project binding captured when this store was validated.

This accessor performs no database read. It is intended for services that must bind a result to the exact root and identity selected at open.

Errors

Returns an error when the store has no complete project binding.

pub fn revalidate_captured_project_binding(&self) -> DbResult<()>

Revalidate the captured binding against a fresh database snapshot.

File-backed stores open an independent read-only snapshot so a report connection pinned to an older WAL end mark cannot hide a concurrent same-root identity rotation. In-memory stores validate their only connection because no external database binding exists.

Errors

Returns an error when the database, root, identity, schema, or filesystem binding no longer matches the state captured at open.

pub fn begin_index_publication( &mut self, contract_fingerprint: &str, ) -> DbResult<IndexPublicationGuard<'_>>

Begin one exclusive full derived-index publication.

Every nested projection write remains inside the returned guard’s SQLite transaction. Other connections keep the prior complete generation queryable until IndexPublicationGuard::complete commits.

Errors

Returns an error if the exclusive write transaction cannot begin.

pub fn begin_index_publication_from( &mut self, contract_fingerprint: &str, expected_base_generation: IndexGeneration, ) -> DbResult<IndexPublicationGuard<'_>>

Begin one exclusive full derived-index publication only when its prepared base generation is still current.

[IndexGeneration::ZERO] matches only an uninitialized store. The generation comparison occurs after BEGIN IMMEDIATE and before any publication metadata or projection row is changed.

Errors

Returns an error if the exclusive write transaction cannot begin or another publisher completed a newer generation after work was prepared.

pub fn begin_index_projection_refresh( &mut self, contract_fingerprint: &str, ) -> DbResult<IndexPublicationGuard<'_>>

Begin one exclusive symbol/projection refresh without replacing the established full-index contract.

Errors

Returns an error if the index is incomplete, the established contract differs, or the exclusive write transaction cannot begin.

pub fn begin_index_projection_refresh_from( &mut self, contract_fingerprint: &str, expected_base_generation: IndexGeneration, ) -> DbResult<IndexPublicationGuard<'_>>

Begin one exclusive symbol/projection refresh only when its prepared base generation is still current.

Errors

Returns an error if the index is incomplete, the established contract differs, the base generation changed, or the exclusive write transaction cannot begin.

pub fn begin_index_read_snapshot(&self) -> DbResult<()>

Start one stable read snapshot for freshness verification and every subsequent query used to construct the response.

Errors

Returns an error if a snapshot is already active or SQLite cannot begin the transaction.

pub fn finish_index_read_snapshot(&self) -> DbResult<()>

Finish an active read snapshot before an optional telemetry write.

This method is a no-op for stores that were not opened for a normal freshness-verified read.

Errors

Returns an error if SQLite cannot finish the read transaction.

pub fn index_publication(&self) -> DbResult<Option<IndexPublication>>

Load the current derived-index publication state when initialized.

Errors

Returns an error if metadata is invalid or cannot be read.

pub fn replace_symbol_graph(&mut self, graph: &SymbolGraph) -> DbResult<()>

Replace the symbol graph for a file path.

Errors

Returns an error if persistence fails.

pub fn replace_symbol_graph_with_metadata( &mut self, graph: &SymbolGraph, metadata: &SourceParseMetadata, ) -> DbResult<()>

Replace one file’s symbol graph while preserving independent source parse metadata.

This permits a grammar-backed source parse to coexist with conservative fallback symbol and relationship facts without relabeling those facts as grammar-native.

Errors

Returns an error if metadata identity/counts differ from the graph or persistence fails.

pub fn clear_source_index_for_path(&self, path: &str) -> DbResult<()>

Clear source-derived intelligence for one live file path.

This removes symbols, relations, and the node-level content summary so skipped or failed parser work cannot leave stale source facts visible.

Errors

Returns an error if the path does not exist or persistence fails.

pub fn clear_symbol_graph_for_path(&self, path: &str) -> DbResult<()>

Clear symbols and relations for one live file path while preserving node summaries.

Errors

Returns an error if persistence fails.

pub fn set_node_summary(&self, path: &str, summary: &str) -> DbResult<()>

Persist an observed one-line summary for an indexed node.

Errors

Returns an error if the path does not exist or persistence fails.

pub fn clear_node_summary(&self, path: &str) -> DbResult<()>

Remove the observed node-level summary for an indexed node.

Errors

Returns an error if the path does not exist or persistence fails.

pub fn load_symbols( &self, file: Option<&str>, query: Option<&str>, limit: usize, ) -> DbResult<Vec<CodeSymbol>>

Load symbols filtered by optional file path and query.

Errors

Returns an error if reading fails.

pub fn load_symbols_for_paths_bounded( &self, paths: &[String], budget: SymbolBatchReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<SymbolBatchRead>

Load one bounded deterministic symbol set for exact repository paths.

The request uses indexed symbols.path predicates, chunks bindings below the SQLite variable ceiling, and preserves the store’s active read snapshot. The service remains responsible for matching exact declaration identities within these admitted owning paths.

Errors

Returns an error when a path/budget is invalid, cancellation or the request deadline fires, a row is corrupt, or SQLite iteration fails.

pub fn load_symbols_by_kinds( &self, file: &str, kinds: &[SymbolKind], limit: usize, ) -> DbResult<Vec<CodeSymbol>>

Load symbols for a file and one or more exact kinds.

Errors

Returns an error if reading fails.

pub fn count_symbols_by_kinds( &self, file: &str, kinds: &[SymbolKind], ) -> DbResult<usize>

Count symbols for a file and one or more exact kinds.

Errors

Returns an error if reading fails.

pub fn symbol_name_counts( &self, names: &[String], ) -> DbResult<HashMap<String, usize>>

Count indexed symbols grouped by exact name.

Errors

Returns an error if reading fails.

pub fn load_symbols_by_names( &self, names: &[String], ) -> DbResult<Vec<CodeSymbol>>

Load symbols with exact names.

Errors

Returns an error if reading fails.

pub fn load_exported_symbol_names_for_path( &self, file: &str, limit: usize, ) -> DbResult<Vec<String>>

Load exported symbol names for one file.

Errors

Returns an error if reading fails.

pub fn exported_symbol_count_for_path(&self, file: &str) -> DbResult<usize>

Count exported symbol names for one file.

Errors

Returns an error if reading fails.

pub fn load_symbol_by_name( &self, file: &str, name: &str, ) -> DbResult<Option<CodeSymbol>>

Load one symbol by exact file and name.

Errors

Returns an error if reading fails.

pub fn load_symbols_by_exact_file_and_name( &self, file: &str, name: &str, ) -> DbResult<Vec<CodeSymbol>>

Load all symbols with an exact file and name.

Errors

Returns an error if reading fails.

pub fn load_node_by_path(&self, path: &str) -> DbResult<Option<IndexedNode>>

Load one existing node with purpose state by repository path.

Errors

Returns an error if reading or enum conversion fails.

pub fn load_nodes_by_paths( &self, paths: &[String], ) -> DbResult<Vec<IndexedNode>>

Load existing nodes for exact repository paths.

Errors

Returns an error if reading or enum conversion fails.

pub fn load_nodes_by_paths_controlled( &self, paths: &[String], control: Option<&IndexWorkControl>, ) -> DbResult<Vec<IndexedNode>>

Load existing nodes for exact repository paths in bounded cancellable batches.

Errors

Returns an error if cancellation fires or reading or enum conversion fails.

pub fn load_purpose_owner_nodes_by_paths_controlled( &self, project: ProjectInstanceId, generation: IndexGeneration, paths: &[String], budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphReadBatch<IndexedNode>>

Hydrate every exact purpose-owner path under one graph read envelope.

Rows are returned in caller order. Unlike the compatibility path loader, this graph-facing boundary evaluates every unique requested path in the selected project and generation. Existing rows retain caller order; absent ancestor candidates are represented by omission rather than a partial-query failure.

Errors

Returns an error for duplicate paths, a stale project or generation, cancellation, corrupt node or purpose state, SQLite failure, or any returned-row, decoded-byte, or hydrated-path budget overrun. No partial batch is returned.

pub fn load_purpose_curation_batch( &self, task: &str, paths: &[String], ) -> DbResult<PurposeCurationBatch>

Load one bounded stale-safe purpose-curation batch for exact paths.

The node hydration is one prepared set query regardless of row count. Accepted purposes are intentionally omitted from curator work.

Errors

Returns an error for an invalid task, oversized batch, changed project binding, invalid persisted state, or failed SQLite read.

pub fn load_symbol_relations( &self, file: Option<&str>, query: Option<&str>, limit: usize, ) -> DbResult<Vec<SymbolRelation>>

Load symbol relations filtered by optional file path and query.

Errors

Returns an error if reading fails.

pub fn load_symbol_relations_by_kind( &self, file: &str, kind: RelationKind, limit: usize, ) -> DbResult<Vec<SymbolRelation>>

Load symbol relations for a file and exact relation kind.

Errors

Returns an error if reading fails.

pub fn count_symbol_relations_by_kind( &self, file: &str, kind: RelationKind, ) -> DbResult<usize>

Count symbol relations for a file and exact relation kind.

Errors

Returns an error if reading fails.

pub fn load_distinct_relation_targets_by_kind( &self, file: &str, kind: RelationKind, limit: usize, ) -> DbResult<Vec<String>>

Load distinct relation targets for a file and exact relation kind.

Errors

Returns an error if reading fails.

pub fn count_distinct_relation_targets_by_kind( &self, file: &str, kind: RelationKind, ) -> DbResult<usize>

Count distinct relation targets for a file and exact relation kind.

Errors

Returns an error if reading fails.

pub fn load_call_relations_to_targets( &self, target_names: &[String], limit_per_target: usize, ) -> DbResult<Vec<SymbolRelation>>

Load call relations targeting any of the requested symbol names.

Errors

Returns an error if reading fails.

pub fn load_import_relations_matching_targets( &self, terms: &[String], limit_per_term: usize, ) -> DbResult<Vec<StoredImportRelation>>

Load import relations whose persisted target text mentions any term.

Errors

Returns an error if reading fails.

pub fn load_import_relations_for_path( &self, path: &str, limit: usize, ) -> DbResult<Vec<StoredImportRelation>>

Load bounded import facts for one exact caller path.

Errors

Returns an error if the covering indexed read fails.

pub fn symbol_count(&self) -> DbResult<usize>

Count persisted symbols.

Errors

Returns an error if reading fails.

pub fn symbol_relation_count(&self) -> DbResult<usize>

Count persisted symbol relations.

Errors

Returns an error if reading fails.

pub fn symbol_count_for_path(&self, path: &str) -> DbResult<usize>

Count persisted symbols for one file path.

Errors

Returns an error if reading fails.

pub fn symbol_counts_for_paths( &self, paths: &[String], ) -> DbResult<HashMap<String, usize>>

Count persisted symbols for a batch of file paths.

Paths without symbols are omitted from the returned map.

Errors

Returns an error if reading fails.

pub fn source_parse_metadata_paths_for_paths( &self, paths: &[String], ) -> DbResult<HashSet<String>>

Return exact paths with persisted parser metadata from one bounded path set.

Errors

Returns an error if reading or row decoding fails.

pub fn symbol_parser_kinds_for_path( &self, path: &str, ) -> DbResult<Vec<ParserKind>>

Return distinct parser strategies that produced symbols for one path.

Errors

Returns an error if reading fails.

pub fn load_symbol_graphs_for_paths( &self, paths: &[String], ) -> DbResult<Vec<SymbolGraph>>

Reconstruct persisted symbol graphs for exact repository paths in bounded batches.

Paths without parser metadata are omitted. Any selected symbol or relation without matching metadata, or any metadata count mismatch, fails the whole operation instead of returning a partial graph set.

Errors

Returns an error for SQLite failures, invalid persisted counts or enums, and inconsistent symbol-graph rows.

pub fn load_source_parse_metadata( &self, path: &str, ) -> DbResult<Option<SourceParseMetadata>>

Load file-level parser metadata for one path.

Errors

Returns an error if reading fails or stored counts are invalid.

pub fn max_symbol_end_line_for_path(&self, path: &str) -> DbResult<usize>

Load the maximum indexed symbol end line for one file path.

Errors

Returns an error if reading fails.

pub fn has_agent_approved_purpose(&self) -> DbResult<bool>

Return whether any accepted agent-authored purpose can affect navigation.

Errors

Returns an error when the bounded indexed lookup fails.

pub fn set_purpose( &self, path: &str, purpose: &str, source: PurposeSource, ) -> DbResult<()>

Persist a purpose for a path.

Errors

Returns an error if the path does not exist or persistence fails.

pub fn authored_purpose_revision(&self) -> DbResult<u64>

Return the accepted authored-purpose revision captured by this connection.

Databases created before the revision contract have revision zero until their first accepted purpose mutation.

Errors

Returns an error when the metadata value is corrupt.

pub fn conditionally_set_purpose( &self, task: &str, path: &str, work_key: &str, state_token: &str, purpose: &str, ) -> DbResult<PurposeConditionalApplyState>

Approve one purpose only while its curator work and unapproved row are current.

This path never changes an accepted purpose. Call Self::set_purpose for a deliberate correction after an agent or user identifies one.

Errors

Returns an error for invalid task input, binding/schema failure, or a failed atomic SQLite transaction. Stale and accepted rows are returned as typed non-error states.

pub fn conditionally_set_purposes( &self, requests: &[PurposeConditionalApplyRequest], ) -> DbResult<Vec<PurposeConditionalApplyResult>>

Apply a bounded stale-safe purpose-review batch in one writer transaction.

Current-row lookup and conditional-update statements are cached and reused for every item. A stale item leaves independent matching rows eligible within the same host-owned batch.

Errors

Returns an error for invalid task input, oversized input, binding/schema failure, or any failed statement/commit. A database error rolls back the complete batch.

pub fn set_suggested_purpose(&self, path: &str, purpose: &str) -> DbResult<()>

Persist a non-approved purpose suggestion for a path.

Errors

Returns an error if the path does not exist or persistence fails.

pub fn load_nodes(&self) -> DbResult<Vec<IndexedNode>>

Load existing nodes with purpose state.

Errors

Returns an error if reading or enum conversion fails.

pub fn load_ranked_nodes( &self, query: &str, kind: NodeKind, folder: Option<&str>, limit: usize, offset: usize, ) -> DbResult<Vec<IndexedNode>>

Load a bounded ranked node list directly from SQLite.

This is the hot path for agent orientation commands. It keeps large repositories from materializing every indexed path just to answer a top-N folder or file query.

Errors

Returns an error if reading or enum conversion fails.

pub fn source_file_byte_count(&self, folder: Option<&str>) -> DbResult<usize>

Sum indexed source bytes represented by file nodes.

Errors

Returns an error if reading fails or the aggregate cannot fit in usize.

pub fn visit_file_token_estimates<F>( &self, folder: Option<&str>, visitor: F, ) -> DbResult<()>

where F: FnMut(String, Option<u64>) -> DbResult<bool>,

Visit indexed file paths and source sizes for exact token baselines.

Errors

Returns an error if reading fails, stored counts are invalid, or the visitor returns an error.

pub fn unresolved_health_findings( &self, resolved_ids: &[String], ) -> DbResult<Vec<HealthFinding>>

Build unresolved health findings without loading the full node table.

Errors

Returns an error if reading fails or stored enum values are invalid.

pub fn unresolved_health_findings_page( &self, resolved_ids: &[String], query: &HealthQuery, ) -> DbResult<HealthFindingsPage>

Build a bounded unresolved health findings page.

Errors

Returns an error if reading fails or stored enum values are invalid.

pub fn unresolved_health_findings_page_current( &self, query: &HealthQuery, ) -> DbResult<HealthFindingsPage>

Build a bounded page filtered by this store’s durable resolutions.

Errors

Returns an error if reading fails or stored enum values are invalid.

pub fn purpose_curation_findings_page_current( &self, query: &HealthQuery, ) -> DbResult<HealthFindingsPage>

Build the actionable missing/suggested purpose queue for one low-scope request.

Accepted and legacy-stale purposes are excluded; deliberate accepted-purpose correction remains owned by the explicit purpose-set/review path.

Errors

Returns an error if counting, paging, or stored-state conversion fails.

pub fn unresolved_health_finding_count_current(&self) -> DbResult<usize>

Count all unresolved findings without materializing finding rows or resolution ids.

Errors

Returns an error if reading fails or stored enum values are invalid.

pub fn overview(&self) -> DbResult<Overview>

Compute an overview from the current index.

Errors

Returns an error if the aggregate query fails or a count is invalid.

pub fn record_usage(&self, event: &UsageEvent) -> DbResult<()>

Record a usage event.

Errors

Returns an error if persistence fails.

pub fn record_usage_for_instance( &self, instance_id: UsageInstanceId, owner: UsageInstanceOwner, event: &UsageEvent, seal_after_record: bool, ) -> DbResult<()>

Record a usage event for one bounded runtime or invocation instance.

The internal instance is deliberately separate from the optional caller-visible label carried by [UsageEvent::session_id].

Errors

Returns an error when the selected binding changes, the instance is inactive, a retention bound rejects the event, or SQLite cannot commit the complete telemetry transaction.

pub fn seal_usage_instance(&self, instance_id: UsageInstanceId) -> DbResult<()>

Seal one cleanly completed runtime or invocation instance.

Errors

Returns an error when the selected binding changed, the instance is already inactive, or SQLite cannot commit the state transition.

pub fn telemetry_retention_state(&self) -> DbResult<TelemetryRetentionState>

Return content-free bounded telemetry retention and maintenance state.

Errors

Returns an error when persisted state is missing, corrupt, or cannot be read.

pub fn usage_events( &self, session_id: Option<&str>, ) -> DbResult<Vec<UsageEvent>>

Load usage events.

Errors

Returns an error if loading fails.

pub fn token_overview( &self, session_id: Option<&str>, ) -> DbResult<TokenOverview>

Build a token overview.

Errors

Returns an error if loading events fails.

pub fn token_trends( &self, session_id: Option<&str>, window: TokenTrendWindow, ) -> DbResult<TokenTrendReport>

Build token trend aggregates grouped by day, week, month, or year.

Errors

Returns an error if the window is unsupported or loading events fails.

pub fn resolve_health_finding( &self, resolution: &HealthResolution, ) -> DbResult<()>

Mark a deterministic health finding as agent-resolved.

Errors

Returns an error if the finding is not active or persistence fails.

pub fn resolved_health_ids(&self) -> DbResult<Vec<String>>

Load resolved health finding ids.

Errors

Returns an error if reading fails.

Trait Implementations

impl Deref for IndexPublicationGuard<'_>

type Target = AtlasStore

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for IndexPublicationGuard<'_>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for IndexPublicationGuard<'_>

fn drop(&mut self)

Executes the destructor for this type.