Struct ExecutionCoordinator 

pub struct ExecutionCoordinator { /* private fields */ }

Manages a pool of read-only SQLite connections and executes compiled queries.

Implementations

impl ExecutionCoordinator

pub fn open( path: impl AsRef<Path>, schema_manager: Arc<SchemaManager>, vector_dimension: Option<usize>, pool_size: usize, telemetry: Arc<TelemetryCounters>, ) -> Result<Self, EngineError>

Errors

Returns EngineError if the database connection cannot be opened or schema bootstrap fails.

pub fn database_path(&self) -> &Path

Returns the filesystem path to the SQLite database.

pub fn vector_enabled(&self) -> bool

Returns true when sqlite-vec was loaded and a vector profile is active.

pub fn aggregate_cache_status(&self) -> SqliteCacheStatus

Aggregate SQLite page-cache counters across all pool connections.

Uses try_lock to avoid blocking reads for telemetry reporting. Connections that are currently locked by a query are skipped — this is acceptable for statistical counters.

pub fn execute_compiled_read( &self, compiled: &CompiledQuery, ) -> Result<QueryRows, EngineError>

Errors

Returns EngineError if the SQL statement cannot be prepared or executed.

pub fn execute_compiled_grouped_read( &self, compiled: &CompiledGroupedQuery, ) -> Result<GroupedQueryRows, EngineError>

Errors

Returns EngineError if the root query or any bounded expansion query cannot be prepared or executed.

pub fn read_run(&self, id: &str) -> Result<Option<RunRow>, EngineError>

Read a single run by id.

Errors

Returns EngineError if the query fails or if the connection mutex has been poisoned.

pub fn read_step(&self, id: &str) -> Result<Option<StepRow>, EngineError>

Read a single step by id.

Errors

Returns EngineError if the query fails or if the connection mutex has been poisoned.

pub fn read_action(&self, id: &str) -> Result<Option<ActionRow>, EngineError>

Read a single action by id.

Errors

Returns EngineError if the query fails or if the connection mutex has been poisoned.

pub fn read_active_runs(&self) -> Result<Vec<RunRow>, EngineError>

Read all active (non-superseded) runs.

Errors

Returns EngineError if the query fails or if the connection mutex has been poisoned.

pub fn shape_sql_count(&self) -> usize

Returns the number of shape→SQL entries currently indexed.

Each distinct query shape (structural hash of kind + steps + limits) maps to exactly one SQL string. This is a test-oriented introspection helper; it does not reflect rusqlite’s internal prepared-statement cache, which is keyed by SQL text.

Panics

Panics if the internal shape-SQL-map mutex is poisoned.

pub fn schema_manager(&self) -> Arc<SchemaManager>

Returns a cloned Arc to the schema manager.

pub fn explain_compiled_read(&self, compiled: &CompiledQuery) -> QueryPlan

Return the execution plan for a compiled query without executing it.

Useful for debugging, testing shape-hash caching, and operator diagnostics. Does not open a transaction or touch the database beyond checking the statement cache.

Panics

Panics if the internal shape-SQL-map mutex is poisoned.

pub fn query_provenance_events( &self, subject: &str, ) -> Result<Vec<ProvenanceEvent>, EngineError>

Return all provenance events whose subject matches the given value.

Subjects are logical node IDs (for retire/upsert events) or source_ref values (for excise events).

Errors

Returns EngineError if the query fails or if the connection mutex has been poisoned.

Trait Implementations

impl Debug for ExecutionCoordinator

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

Formats the value using the given formatter.