Struct IndexPublicationGuard 

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

Exclusive parent-owned atomic publication over all derived projections.

Implementations

impl IndexPublicationGuard<'_>

pub fn upsert_file_content_classification_batch( &mut self, rows: &[FileContentClassification], ) -> DbResult<()>

Upsert one bounded classification batch inside the parent publication.

Errors

Returns an error before mutation for duplicate, blank, oversized, absent, inactive, or non-file paths, or when SQLite rejects the batch.

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.

pub fn set_document_unresolved_reasons( &mut self, reasons: &[(LogicalRelationKey, DocumentTargetUnresolvedReason)], ) -> DbResult<()>

Attach closed reasons to unresolved documents relations in this publication.

Call this after the owning graph replacement and before completing the parent publication. The complete input is validated before prepared chunks at or below the graph row ceiling are applied, and every key must select exactly one unresolved documents relation.

Errors

Returns an error before mutation for duplicate keys, or if a key does not identify one compatible relation in the selected project.

pub fn set_document_unresolved_reasons_controlled( &mut self, reasons: &[(LogicalRelationKey, DocumentTargetUnresolvedReason)], control: &IndexWorkControl, ) -> DbResult<()>

Attach document reasons while observing publication cancellation.

Errors

Returns an error without partial mutation when cancellation, duplicate keys, incompatible relations, or SQLite failures occur.

pub fn replace_graph_identity_rejections( &mut self, project: ProjectInstanceId, rejections: &[GraphIdentityRejection], ) -> DbResult<()>

Replace bounded parser identity rejection rows in this publication.

Append the typed details prepared by the graph replacement in this publication. The replacement method clears or rebinds the existing rows before changing graph nodes, so these inserts share its parent transaction; the complete resulting generation must remain within the same row ceiling.

Errors

Returns an error for a foreign project/path, an oversized complete generation, invalid span data, or SQLite failure.

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 file_content_classifications_for_paths( &self, paths: &[String], ) -> DbResult<Vec<FileContentClassification>>

Load classifications for exact file paths in one bounded set of statements.

Errors

Returns an error for an oversized request, missing classification, invalid persisted value, cancellation, or SQLite failure. No partial result is returned.

pub fn file_content_classification_page( &self, classification: ContentClassification, after_path: Option<&str>, limit: u32, ) -> DbResult<FileContentClassificationPage>

Load one stable path page through the classification/path index.

Errors

Returns an error for an invalid limit, corrupt persisted value, or SQLite failure.

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 prepare_worktree_hydration( &self, target_root: &Path, destination_database: &Path, control: &IndexWorkControl, ) -> DbResult<WorktreeHydrationCandidate>

Prepare one unpublished target-local worktree database through SQLite online backup.

The caller must first prove through structural Git evidence that source and target belong to the same repository. The returned candidate must be reconciled with the normal scan pipeline before WorktreeHydrationCandidate::activate will publish it.

Errors

Returns an error for incompatible source state, unsafe target placement, an existing destination, cancellation/deadline, backup contention, invalid copied state, or I/O.

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_graph_entrypoint_candidates_page_bounded( &self, project: ProjectInstanceId, generation: IndexGeneration, limit: u32, selection: ContentSelection, budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphReadPage<GraphEntity>>

Load a bounded stable-order page of local entrypoint candidate entities.

This read is intentionally page-shaped and has no persistence side effects. Callers use the truncation sentinel to refuse conclusions when the complete entity scope does not fit its declared bound.

Errors

Returns a database error when the requested snapshot is unavailable, the limit or budget is invalid, the read is cancelled, or SQLite cannot execute the bounded query.

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_resolved_relation_hubs( &self, relation: GraphRelationKind, limit: u32, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphPage<GraphEntity>>

Load the highest-degree resolved endpoints for one relation family.

Ranking considers every exact local resolution from the current publication while hydrating only the requested bounded endpoint page. Self-relations are excluded because they cannot expand a preview.

Errors

Returns an error for invalid limits, cancellation, SQLite failure, or any corrupt entity 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_classified_relation_family_rows( &self, relation: GraphRelationKind, selection: ContentSelection, limit: u32, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphPage<RepositoryGraphClassifiedRelationRow>>

Load one relation-family page with pre-limit source classification selection.

Omitted selection preserves the existing family candidate universe and relation-key order. Explicit selection filters file-bearing source entities inside the indexed relation query before LIMIT; the returned source classification is projected by the same statement.

Errors

Returns an error for invalid limits, cancellation, SQLite failures, missing or corrupt source classifications, or corrupt graph rows. No partial page is returned.

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 legacy 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.

An unfiltered request preserves the legacy family set and excludes documents; an exact documents request remains selectable.

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_resolved_adjacency_page( &self, frontier: &[GraphEntityKey], direction: RepositoryGraphDirection, relation: GraphRelationKind, continuation: Option<&RepositoryGraphAdjacencyContinuation>, limit: u32, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphAdjacencyPage>

Load one bounded exact-family adjacency page containing only local resolutions.

Errors

Returns the same fail-closed errors as Self::repository_graph_adjacency_page_filtered and binds the local resolution filter 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 legacy family-filtered adjacency page and report exact database work.

An unfiltered request excludes documents before limits are applied.

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_adjacency_page_filtered_bounded_with_documents( &self, frontier: &[GraphEntityKey], direction: RepositoryGraphDirection, relation: Option<GraphRelationKind>, include_documents: bool, continuation: Option<&RepositoryGraphAdjacencyContinuation>, limit: u32, budget: RepositoryGraphReadBudget, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphAdjacencyReadPage>

Load one family-filtered adjacency page with explicit document visibility.

include_documents affects only an unfiltered request. An exact documents family always remains selectable. The effective choice is applied before branch limits and bound into continuation identity.

Errors

Returns the same fail-closed errors and bounded-work accounting as Self::repository_graph_adjacency_page_filtered_bounded.

pub fn repository_graph_adjacency_is_empty( &self, key: &GraphEntityKey, direction: RepositoryGraphDirection, relation: GraphRelationKind, control: Option<&IndexWorkControl>, ) -> DbResult<bool>

Check one exact relation family without admitting or decoding a row.

This is the terminal probe used when a bounded traversal has exhausted its edge allowance. It distinguishes an empty adjacency from a pending edge without granting the caller another ordinary adjacency row.

Errors

Returns an error for an invalid entity key, cancellation, or a SQLite failure.

pub fn repository_graph_adjacency_is_empty_filtered( &self, key: &GraphEntityKey, direction: RepositoryGraphDirection, relation: GraphRelationKind, minimum_confidence: ConfidenceClass, selection: ContentSelection, control: Option<&IndexWorkControl>, ) -> DbResult<bool>

Check one exact relation family after applying confidence and endpoint content admission without decoding or admitting a row.

This is the bounded terminal probe used by callers that must distinguish an empty admitted frontier from a pending relation without consuming an ordinary traversal edge.

Errors

Returns an error for an invalid entity key, cancellation, or a SQLite failure.

pub fn repository_graph_adjacency_continuation_has_filtered_rows( &self, continuation: &RepositoryGraphAdjacencyContinuation, minimum_confidence: ConfidenceClass, selection: ContentSelection, control: Option<&IndexWorkControl>, ) -> DbResult<bool>

Check whether a prior adjacency page has any admitted rows remaining.

The continuation is validated against its original project, generation, direction, family, and frontier. No relation row is decoded or charged to the caller’s ordinary page budget.

Errors

Returns an error for a stale or invalid continuation, cancellation, or a SQLite failure.

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_coverage_page_controlled( &self, project: ProjectInstanceId, query: &RepositoryCoverageQuery, control: Option<&IndexWorkControl>, ) -> DbResult<RepositoryGraphPage<RepositoryCoverageRow>>

Discover coverage through the shared cancellation and deadline boundary.

Errors

Returns the same errors as Self::repository_coverage_page plus typed cancellation or deadline failure while SQLite is scanning candidates.

pub fn repository_graph_identity_rejections( &self, project: ProjectInstanceId, paths: &[RepositoryNodePath], limit: u32, control: Option<&IndexWorkControl>, ) -> DbResult<Vec<GraphIdentityRejection>>

Load bounded typed identity rejections for the current graph generation.

Errors

Returns an error for invalid bounds or paths, unavailable publication state, project mismatch, cancellation, SQLite failure, or corrupt persisted rejection data.

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 register_worktree( &self, alias: &WorktreeAlias, git_common_directory: &Path, git_administrative_directory: &Path, git_administrative_identity: &str, root: &Path, project_instance_id: Option<ProjectInstanceId>, created_at_epoch: u64, ) -> DbResult<WorktreeRegistration>

Register one structurally validated non-control Git worktree.

A matching retired row is reactivated only when its administrative and project identities still agree. Historical rows for a replaced atlas remain retired so their aggregate telemetry cannot be relabelled.

Errors

Returns an error for invalid paths/times, active alias or identity conflicts, malformed persisted state, or any transactional SQLite failure.

pub fn register_worktree_with_usage_snapshot( &self, alias: &WorktreeAlias, git_common_directory: &Path, git_administrative_directory: &Path, git_administrative_identity: &str, root: &Path, project_instance_id: ProjectInstanceId, snapshot: &WorktreeUsageSnapshot, created_at_epoch: u64, ) -> DbResult<(WorktreeRegistration, WorktreeUsageSyncState)>

Register one initialized worktree and import its captured usage atomically.

Errors

Returns any registration or snapshot synchronization error without making the registration visible.

pub fn refresh_worktree_root( &self, registration: &WorktreeRegistration, root: &Path, ) -> DbResult<WorktreeRegistration>

Refresh the canonical root of one captured active registration.

Errors

Returns an error when the captured registration is no longer active, the root is invalid, persisted state is malformed, or SQLite fails.

pub fn worktree_registration( &self, alias: &WorktreeAlias, ) -> DbResult<WorktreeRegistration>

Return one active registration by alias.

Errors

Returns an error when the alias is absent, a persisted row is malformed, or SQLite cannot complete the read.

pub fn worktree_registrations( &self, include_retired: bool, ) -> DbResult<Vec<WorktreeRegistration>>

List active registrations and optionally retained retired history.

Errors

Returns an error for malformed persisted rows or SQLite read failures.

pub fn with_matching_active_worktree_catalog<T>( &self, expected: &[WorktreeRegistration], operation: impl FnOnce() -> DbResult<T>, ) -> DbResult<Option<T>>

Run one short operation when active catalog identities still match.

Errors

Returns None when the active row count, order, aliases, or project bindings changed. Returns an error for malformed persisted rows, a changed database binding, an operation failure, or any SQLite transaction failure.

pub fn with_active_worktree_registration<T>( &self, registration_id: i64, alias: &WorktreeAlias, operation: impl FnOnce(&mut ActiveWorktreeRegistrationGuard<'_>) -> DbResult<T>, ) -> DbResult<T>

Run one short operation while an exact active registration owns control-writer exclusion.

Callers that coordinate another local atlas must acquire this scope first, then open or lock the local atlas, and finally publish through this guard before returning.

Errors

Returns an error when the captured registration is no longer active under the same alias, the control database binding changed, the callback fails, or SQLite cannot commit or roll back the transaction.

pub fn with_unbound_worktree_registration<T, E>( &self, registration_id: i64, alias: &WorktreeAlias, operation: impl FnOnce(&WorktreeRegistration) -> Result<T, E>, ) -> DbResult<Result<T, E>>

Run one external reset operation while an exact registration remains unbound.

The callback must not mutate the control catalog. Its nested result keeps caller-owned filesystem errors typed while the outer result owns SQLite validation and transaction failures.

Errors

Returns an error when the captured registration is no longer active under the same alias, became bound, the control binding changed, or SQLite cannot complete the writer-exclusion transaction.

pub fn export_worktree_usage_snapshot(&self) -> DbResult<WorktreeUsageSnapshot>

Export this exact atlas’s bounded local aggregate snapshot.

Errors

Returns an error when the selected database binding is invalid, stored aggregate state is corrupt, a bound is exceeded, or SQLite cannot read one complete snapshot.

pub fn with_exclusive_worktree_usage_snapshot<T>( &self, operation: impl FnOnce(&WorktreeUsageSnapshot) -> DbResult<T>, ) -> DbResult<T>

Hold local writer exclusion while a caller consumes one exact usage snapshot.

The callback must remain short: its lifetime is the final-synchronization boundary that prevents a local usage commit from landing between export and control-atlas retirement.

Errors

Returns an error when the exact database binding changed, writer exclusion cannot be acquired, snapshot export fails, or the callback fails.

pub fn synchronize_worktree_usage( &self, alias: &WorktreeAlias, snapshot: &WorktreeUsageSnapshot, ) -> DbResult<WorktreeUsageSyncState>

Accept a strictly newer local aggregate snapshot for one active alias.

Errors

Returns an error for an absent alias, mismatched project identity, malformed or excessive snapshot state, changed control binding, or any transactional SQLite failure. The last accepted snapshot remains intact on every error.

pub fn bind_worktree_project( &self, registration_id: i64, alias: &WorktreeAlias, root: &Path, project_instance_id: ProjectInstanceId, ) -> DbResult<WorktreeRegistration>

Bind an initialized worktree identity to one captured active registration.

Errors

Returns an error when the captured registration is no longer active under the same alias, its project identity conflicts, the path is invalid, stored state is malformed, or SQLite fails.

pub fn retire_worktree( &self, registration_id: i64, alias: &WorktreeAlias, retired_at_epoch: u64, ) -> DbResult<WorktreeRegistration>

Retire one active alias without deleting its aggregate history.

The caller owns required final telemetry synchronization before invoking this storage transition.

Errors

Returns an error when the captured registration is no longer active under the same alias, the time or stored state is invalid, or SQLite fails.

pub fn retire_worktree_with_usage_snapshot( &self, registration_id: i64, alias: &WorktreeAlias, root: &Path, project_instance_id: ProjectInstanceId, snapshot: &WorktreeUsageSnapshot, retired_at_epoch: u64, ) -> DbResult<(WorktreeRegistration, WorktreeUsageSyncState)>

Bind, synchronize one writer-excluded local snapshot, and retire its alias atomically.

Errors

Returns an error for an absent alias, mismatched snapshot identity, invalid time or aggregate state, changed control binding, or transactional SQLite failure. Binding, synchronization, and retirement roll back together.

pub fn begin_purpose_mutation(&self) -> DbResult<PurposeMutationTransaction<'_>>

Begin one purpose mutation whose caller owns final source revalidation.

Purpose writes performed through this store join the returned immediate transaction. The caller must revalidate its saved-source witness before committing; an early return drops the guard and rolls the complete batch back.

Errors

Returns an error when mutation is unavailable, the binding changed, or SQLite cannot start the 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 project_root_identity(&self) -> DbResult<Option<CanonicalProjectRoot>>

Load the authoritative native project-root identity.

Errors

Returns an error when the identity row cannot be read or its versioned codec payload is invalid.

pub fn project_root_identity_matches( &self, selected: &CanonicalProjectRoot, ) -> bool

Return whether a selected canonical root resolves to this store’s captured native root identity.

The comparison re-canonicalizes both existing roots through the admission proof, so case-only spelling changes on case-insensitive filesystems are accepted while distinct case-sensitive roots remain different. An unavailable or unresolvable persisted root fails closed.

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 probe_index_publication_writer(&mut self) -> DbResult<()>

Check publication-writer availability without changing durable state.

The probe uses the same fail-fast acquisition policy as a real publication and immediately rolls back a successful transaction. It lets callers reject a contended writer before doing expensive staging, while preserving the complete generation for every connection.

Errors

Returns an error when the exclusive writer cannot be acquired or the probe transaction cannot be rolled back.

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_classified_symbols( &self, file: Option<&str>, query: Option<&str>, selection: ContentSelection, limit: usize, ) -> DbResult<Vec<ClassifiedSymbol>>

Load symbols with their owning file classification and optional content selection.

Omitted selection retains the legacy symbol candidate universe and order. Explicit selection is applied by SQLite before the row limit.

Errors

Returns an error if a classification is missing or corrupt, or 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 record_usage_for_worktree_instance( &self, instance_id: UsageInstanceId, owner: UsageInstanceOwner, registration_id: i64, event: &UsageEvent, seal_after_record: bool, ) -> DbResult<()>

Record one centrally routed event for a captured worktree registration.

Errors

Returns an error when the selected control binding changes, the registration or runtime origin conflicts, 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 repository_token_overview(&self) -> DbResult<TokenOverview>

Build the control atlas’s combined native-main and synchronized-worktree overview.

Errors

Returns an error when the selected binding or aggregate state is invalid, arithmetic overflows, or SQLite cannot complete the bounded read.

pub fn registered_worktree_token_overview( &self, alias: &WorktreeAlias, ) -> DbResult<TokenOverview>

Build exact retained routed plus synchronized totals for one active alias.

Errors

Returns an error when the alias is absent, aggregate state is invalid, arithmetic overflows, or SQLite cannot complete the bounded read.

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 repository_token_trends( &self, window: TokenTrendWindow, ) -> DbResult<TokenTrendReport>

Build combined native-main and synchronized-worktree token trends.

Errors

Returns an error for an unsupported window, invalid aggregate state, arithmetic overflow, or a bounded SQLite read failure.

pub fn registered_worktree_token_trends( &self, alias: &WorktreeAlias, window: TokenTrendWindow, ) -> DbResult<TokenTrendReport>

Build exact retained routed plus synchronized trends for one active alias.

Errors

Returns an error when the alias is absent, the window or aggregate state is invalid, arithmetic overflows, or SQLite cannot complete the read.

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.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.