Struct AdminService 

pub struct AdminService { /* private fields */ }

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

Implementations

impl AdminService

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

impl AdminService

pub fn capabilities() -> Capabilities

Return the static install/build surface. Does not open the DB.

pub fn current_config(&self) -> Result<CurrentConfig, EngineError>

Return a snapshot of runtime configuration: active embedding profile, all vector_index_schemas rows, all FTS profiles, and aggregate work-queue counts.

Aggregates only — all underlying tables are already individually queryable via other admin methods. Single read transaction.

Errors

Returns EngineError on database failure.

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

Return a per-kind view: vector config, FTS config, chunk count, and vec-row count (if the per-kind vec table exists).

Errors

Returns EngineError on database failure.

impl AdminService

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.

impl AdminService

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.

impl AdminService

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 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 configure_vec_kind( &self, kind: &str, source: VectorSource, ) -> Result<ConfigureVecOutcome, EngineError>

Configure per-kind vector indexing for kind, sourced from source.

Requires at least one active row in vector_embedding_profiles. On first call, creates the vec_<kind> sqlite-vec table, inserts a vector_index_schemas row, and enqueues backfill rows in vector_projection_work (one per existing chunk of that kind). Subsequent calls are idempotent: no duplicate pending work rows are created for the (chunk_id, embedding_profile_id) pair.

Errors

Returns EngineError::InvalidConfig if no active embedding profile exists; EngineError::Sqlite/EngineError::Schema on storage failures.

pub fn configure_vec_kinds( &self, items: &[(String, VectorSource)], ) -> Result<Vec<ConfigureVecOutcome>, EngineError>

Batch form of Self::configure_vec_kind. Loops over each (kind, source) in input order and returns one outcome per entry.

Per-kind atomicity matches Self::configure_vec_kind: each call runs its own transaction. The batch as a whole is not atomic — if the third call fails, the first two remain committed.

Errors

Returns the first EngineError encountered; already-committed entries remain committed.

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

Return the managed vector indexing status for kind.

If no vector_index_schemas row exists for kind, returns enabled = false and state = "unconfigured" with zero counts.

Errors

Returns EngineError on database failures.

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 configure_embedding( &self, embedder: &dyn QueryEmbedder, acknowledge_rebuild_impact: bool, ) -> Result<ConfigureEmbeddingOutcome, EngineError>

Activate, replace, or confirm the database-wide embedding identity.

Vector identity belongs to the embedder: the model_identity, model_version, dimensions, and normalization_policy persisted in vector_embedding_profiles are read directly from embedder.identity(). Callers cannot supply an identity string.

Semantics:

• If no active profile exists: insert a new active row. Returns ConfigureEmbeddingOutcome::Activated.
• If an active profile exists and the identity matches exactly: no-op. Returns ConfigureEmbeddingOutcome::Unchanged.
• If an active profile exists and the identity differs:
  • If any vector_index_schemas.enabled = 1 rows exist and acknowledge_rebuild_impact = false: return EngineError::EmbeddingChangeRequiresAck without mutating state.
  • Otherwise, within a single transaction: demote the current active profile, insert the new active profile, and mark every enabled vector index schema state = 'stale'. Returns ConfigureEmbeddingOutcome::Replaced.

This method never triggers a rebuild itself. Affected kinds are marked stale so later rebuild flows can pick them up.

Errors

• EngineError::EmbeddingChangeRequiresAck if the identity change would invalidate enabled vector index kinds and the caller did not acknowledge the rebuild impact.
• EngineError::Sqlite if any underlying SQL fails.

pub fn active_embedding_profile_id(&self) -> Result<Option<i64>, EngineError>

Return the active vector_embedding_profiles.profile_id, or None if no active profile is configured.

Errors

Returns EngineError if the database read fails.

pub fn drain_vector_projection( &self, embedder: &dyn BatchEmbedder, timeout: Duration, ) -> Result<DrainReport, EngineError>

Run projection-worker scheduling ticks until no more work remains or timeout elapses. Intended for tests and for admin-driven catch-up flows.

Errors

Returns EngineError on writer or database failures, or EngineError::InvalidConfig if the admin service was constructed without a writer handle.

pub fn drain_vector_projection_single_tick( &self, embedder: &dyn BatchEmbedder, ) -> Result<DrainReport, EngineError>

Run exactly one projection scheduling tick; used by tests that need to assert priority ordering.

Errors

Returns EngineError on writer or database failures.

pub fn check_embedding( &self, embedder: &dyn QueryEmbedder, ) -> Result<(), EngineError>

Probe the supplied embedder by attempting a fixed short embed call.

Used as an availability check for the active embedder. Does not touch persistent state.

Errors

Returns EngineError::CapabilityMissing wrapping the embedder diagnostic if the embedder is unavailable or its call fails.

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_client: RebuildClient, ) -> Self

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

pub fn new_with_engine( path: impl AsRef<Path>, schema_manager: Arc<SchemaManager>, rebuild_client: RebuildClient, writer: Arc<WriterActor>, ) -> Self

Create a new admin service wired to the rebuild actor AND a shared writer-actor handle. Used by crate::runtime::EngineRuntime::open so admin surfaces that require writer-thread serialization (e.g. vector projection drain) can submit batches safely.

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.

Trait Implementations

impl Debug for AdminService

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

Formats the value using the given formatter.