Struct AdminService 

pub struct AdminService { /* private fields */ }

Service providing administrative operations (integrity checks, exports, restores, purges).

Implementations

impl AdminService

pub fn new(path: impl AsRef<Path>, schema_manager: Arc<SchemaManager>) -> Self

Create a new admin service for the database at the given path.

pub fn new_with_rebuild( path: impl AsRef<Path>, schema_manager: Arc<SchemaManager>, rebuild_sender: SyncSender<RebuildRequest>, ) -> Self

Create a new admin service wired to the background rebuild actor.

pub fn set_fts_profile( &self, kind: &str, tokenizer_str: &str, ) -> Result<FtsProfile, EngineError>

Persist or update the FTS tokenizer profile for a node kind.

tokenizer_str may be a preset name (see [TOKENIZER_PRESETS]) or a raw FTS5 tokenizer string. The resolved string is validated before being written to projection_profiles.

Errors

Returns EngineError if the tokenizer string contains disallowed characters, or if the database write fails.

pub fn get_fts_profile( &self, kind: &str, ) -> Result<Option<FtsProfile>, EngineError>

Retrieve the FTS tokenizer profile for a node kind.

Returns None if no profile has been set for kind.

Errors

Returns EngineError if the database query fails.

pub fn get_vec_profile( &self, kind: &str, ) -> Result<Option<VecProfile>, EngineError>

Retrieve the vector embedding profile for a specific node kind.

Reads from projection_profiles under (kind=<kind>, facet='vec'). Returns None if no vector profile has been persisted for this kind yet.

Errors

Returns EngineError if the database query fails.

pub fn set_vec_profile( &self, config_json: &str, ) -> Result<VecProfile, EngineError>

Persist or update the global vector profile from a JSON config string.

config_json must be valid JSON with at least a model_identity field and dimensions. The JSON is stored verbatim in the projection_profiles table under kind='*', facet='vec'.

Errors

Returns EngineError if the database write fails.

pub fn preview_projection_impact( &self, kind: &str, facet: &str, ) -> Result<ProjectionImpact, EngineError>

Estimate the cost of rebuilding a projection.

For facet "fts": counts active nodes of kind. For facet "vec": counts all chunks.

Errors

Returns EngineError for unknown facets or database errors.

pub fn check_integrity(&self) -> Result<IntegrityReport, EngineError>

Errors

Returns EngineError if the database connection fails or any SQL query fails.

pub fn check_semantics(&self) -> Result<SemanticReport, EngineError>

Errors

Returns EngineError if the database connection fails or any SQL query fails.

pub fn register_operational_collection( &self, request: &OperationalRegisterRequest, ) -> Result<OperationalCollectionRecord, EngineError>

Errors

Returns EngineError if the collection metadata is invalid or the insert fails.

pub fn describe_operational_collection( &self, name: &str, ) -> Result<Option<OperationalCollectionRecord>, EngineError>

Errors

Returns EngineError if the database query fails.

pub fn update_operational_collection_filters( &self, name: &str, filter_fields_json: &str, ) -> Result<OperationalCollectionRecord, EngineError>

Errors

Returns EngineError if the collection is missing, the filter contract is invalid, or existing mutation backfill fails.

pub fn update_operational_collection_validation( &self, name: &str, validation_json: &str, ) -> Result<OperationalCollectionRecord, EngineError>

Errors

Returns EngineError if the collection is missing or the validation contract is invalid.

pub fn update_operational_collection_secondary_indexes( &self, name: &str, secondary_indexes_json: &str, ) -> Result<OperationalCollectionRecord, EngineError>

Errors

Returns EngineError if the collection is missing, the contract is invalid, or derived index rebuild fails.

pub fn rebuild_operational_secondary_indexes( &self, name: &str, ) -> Result<OperationalSecondaryIndexRebuildReport, EngineError>

Errors

Returns EngineError if the collection is missing or rebuild fails.

pub fn validate_operational_collection_history( &self, name: &str, ) -> Result<OperationalHistoryValidationReport, EngineError>

Errors

Returns EngineError if the collection is missing or its validation contract is invalid.

pub fn disable_operational_collection( &self, name: &str, ) -> Result<OperationalCollectionRecord, EngineError>

Errors

Returns EngineError if the database query fails.

pub fn compact_operational_collection( &self, name: &str, dry_run: bool, ) -> Result<OperationalCompactionReport, EngineError>

Errors

Returns EngineError if the database query fails.

pub fn purge_operational_collection( &self, name: &str, before_timestamp: i64, ) -> Result<OperationalPurgeReport, EngineError>

Errors

Returns EngineError if the database query fails.

pub fn plan_operational_retention( &self, now_timestamp: i64, collection_names: Option<&[String]>, max_collections: Option<usize>, ) -> Result<OperationalRetentionPlanReport, EngineError>

Errors

Returns EngineError if collection selection or policy parsing fails.

pub fn run_operational_retention( &self, now_timestamp: i64, collection_names: Option<&[String]>, max_collections: Option<usize>, dry_run: bool, ) -> Result<OperationalRetentionRunReport, EngineError>

Errors

Returns EngineError if collection selection, policy parsing, or execution fails.

pub fn trace_operational_collection( &self, collection_name: &str, record_key: Option<&str>, ) -> Result<OperationalTraceReport, EngineError>

Errors

Returns EngineError if the database query fails.

pub fn read_operational_collection( &self, request: &OperationalReadRequest, ) -> Result<OperationalReadReport, EngineError>

Errors

Returns EngineError if the collection contract is invalid or the filtered read fails.

pub fn rebuild_operational_current( &self, collection_name: Option<&str>, ) -> Result<OperationalRepairReport, EngineError>

Errors

Returns EngineError if the database query fails or collection validation fails.

pub fn rebuild_projections( &self, target: ProjectionTarget, ) -> Result<ProjectionRepairReport, EngineError>

Errors

Returns EngineError if the database connection fails or the projection rebuild fails.

pub fn rebuild_missing_projections( &self, ) -> Result<ProjectionRepairReport, EngineError>

Errors

Returns EngineError if the database connection fails or the projection rebuild fails.

pub fn register_fts_property_schema( &self, kind: &str, property_paths: &[String], separator: Option<&str>, ) -> Result<FtsPropertySchemaRecord, EngineError>

Register (or update) an FTS property projection schema for the given node kind.

After registration, any node of this kind will have the declared JSON property paths extracted, concatenated, and indexed in the per-kind fts_props_<kind> FTS5 table.

Errors

Returns EngineError if property_paths is empty, contains duplicates, or if the database write fails.

pub fn register_fts_property_schema_with_entries( &self, kind: &str, entries: &[FtsPropertyPathSpec], separator: Option<&str>, exclude_paths: &[String], mode: RebuildMode, ) -> Result<FtsPropertySchemaRecord, EngineError>

Register (or update) an FTS property projection schema with per-path modes and optional exclude paths.

Under RebuildMode::Eager (the legacy mode), the full rebuild runs inside the registration transaction — same behavior as before Pack 7.

Under RebuildMode::Async (the 0.4.1 default), the schema row is persisted in a short IMMEDIATE transaction, a rebuild-state row is upserted, and the actual rebuild is handed off to the background RebuildActor. The register call returns in <100ms even for large kinds.

Errors

Returns EngineError if the paths are invalid, the JSON serialization fails, or the (schema-persist / rebuild) transaction fails.

pub fn get_property_fts_rebuild_state( &self, kind: &str, ) -> Result<Option<RebuildStateRow>, EngineError>

Return the rebuild state row for a kind, if one exists.

Errors

Returns EngineError if the database query fails.

pub fn count_staging_rows(&self, kind: &str) -> Result<i64, EngineError>

Return the count of rows in fts_property_rebuild_staging for a kind. Used by tests to verify the staging table was populated.

Errors

Returns EngineError if the database query fails.

pub fn staging_row_exists( &self, kind: &str, node_logical_id: &str, ) -> Result<bool, EngineError>

Return whether a specific node is present in fts_property_rebuild_staging. Used by tests to verify the double-write path.

Errors

Returns EngineError if the database query fails.

pub fn describe_fts_property_schema( &self, kind: &str, ) -> Result<Option<FtsPropertySchemaRecord>, EngineError>

Return the FTS property schema for a single node kind, if registered.

Errors

Returns EngineError if the database query fails.

pub fn list_fts_property_schemas( &self, ) -> Result<Vec<FtsPropertySchemaRecord>, EngineError>

Return all registered FTS property schemas.

Errors

Returns EngineError if the database query fails.

pub fn remove_fts_property_schema(&self, kind: &str) -> Result<(), EngineError>

Remove the FTS property schema for a node kind.

This does not delete existing FTS rows for this kind; call rebuild_projections(Fts) to clean up stale rows.

Errors

Returns EngineError if the kind is not registered or the delete fails.

pub fn restore_vector_profiles( &self, ) -> Result<ProjectionRepairReport, EngineError>

Recreate enabled vector profiles from persisted vector_profiles metadata.

Errors

Returns EngineError if the database connection fails, reading metadata fails, or sqlite-vec support is unavailable while enabled profiles are present.

pub fn regenerate_vector_embeddings( &self, embedder: &dyn QueryEmbedder, config: &VectorRegenerationConfig, ) -> Result<VectorRegenerationReport, EngineError>

Rebuild vector embeddings using an application-supplied regeneration contract and generator command.

The config is persisted in vector_embedding_contracts so the metadata required for recovery survives future repair runs.

Vector identity is stamped from QueryEmbedder::identity — the caller supplies the embedder and cannot override its identity. This makes drift between the read-path and write-path identity stories structurally impossible.

Errors

Returns EngineError if the database connection fails, the config is invalid, the embedder fails, or the regenerated embeddings are malformed.

pub fn regenerate_vector_embeddings_in_process( &self, embedder: &dyn BatchEmbedder, config: &VectorRegenerationConfig, ) -> Result<VectorRegenerationReport, EngineError>

Regenerate vector embeddings in-process using a [BatchEmbedder].

Functionally equivalent to [regenerate_vector_embeddings] but uses BatchEmbedder::batch_embed to process all chunks in one call. This is the intended path for [BuiltinBgeSmallEmbedder] — it keeps the forward pass in-process without requiring an external subprocess.

The subprocess-based path ([regenerate_vector_embeddings]) remains intact for callers who supply their own generator binary.

Errors

Returns EngineError if the database connection fails, the config is invalid, the embedder fails, or the regenerated embeddings are malformed.

pub fn trace_source(&self, source_ref: &str) -> Result<TraceReport, EngineError>

Errors

Returns EngineError if the database connection fails or any SQL query fails.

pub fn restore_logical_id( &self, logical_id: &str, ) -> Result<LogicalRestoreReport, EngineError>

Errors

Returns EngineError if the database connection fails, the transaction cannot be started, or lifecycle restoration prerequisites are missing.

pub fn purge_logical_id( &self, logical_id: &str, ) -> Result<LogicalPurgeReport, EngineError>

Errors

Returns EngineError if the database connection fails, the transaction cannot be started, or the purge mutation fails.

pub fn purge_provenance_events( &self, before_timestamp: i64, options: &ProvenancePurgeOptions, ) -> Result<ProvenancePurgeReport, EngineError>

Purge provenance events older than before_timestamp.

By default, excise and purge_logical_id event types are preserved so that data-deletion audit trails survive. Pass an explicit preserve_event_types list to override this default.

Errors

Returns EngineError if the database connection fails, the transaction cannot be started, or any SQL statement fails.

pub fn excise_source( &self, source_ref: &str, ) -> Result<TraceReport, EngineError>

Errors

Returns EngineError if the database connection fails, the transaction cannot be started, or any SQL statement fails.

pub fn safe_export( &self, destination_path: impl AsRef<Path>, options: SafeExportOptions, ) -> Result<SafeExportManifest, EngineError>

Errors

Returns EngineError if the WAL checkpoint fails, the SQLite backup fails, the SHA-256 digest cannot be computed, or the manifest file cannot be written.

Trait Implementations

impl Debug for AdminService

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.