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>, query_embedder: Option<Arc<dyn QueryEmbedder>>, ) -> 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_search( &self, compiled: &CompiledSearch, ) -> Result<SearchRows, EngineError>

Execute a compiled adaptive search and return matching hits.

Phase 2 splits filters: fusable predicates (KindEq, LogicalIdEq, SourceRefEq, ContentRefEq, ContentRefNotNull) are injected into the search_hits CTE so the CTE LIMIT applies after filtering, while residual predicates (JSON path filters) stay in the outer WHERE. The chunk and property FTS indexes are UNION ALL-ed, BM25-scored (flipped so larger values mean better matches), ordered, and limited. All hits return match_mode = Strict — the relaxed branch and fallback arrive in later phases.

Errors

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

pub fn execute_compiled_search_plan( &self, plan: &CompiledSearchPlan, ) -> Result<SearchRows, EngineError>

Execute a two-branch CompiledSearchPlan and return the merged, deduped result rows.

This is the shared retrieval/merge routine that both Self::execute_compiled_search (adaptive path) and Engine::fallback_search (narrow two-shape path) call into. Strict runs first; the relaxed branch only fires when it is present AND the strict branch returned fewer than min(FALLBACK_TRIGGER_K, limit) hits. Merge and dedup semantics are identical to the adaptive path regardless of how the plan was constructed.

Error contract: if the relaxed branch errors, the error propagates; strict hits are not returned. This matches the rest of the engine’s fail-hard posture.

Errors

Returns EngineError if either branch’s SQL cannot be prepared or executed.

pub fn execute_compiled_vector_search( &self, compiled: &CompiledVectorSearch, ) -> Result<SearchRows, EngineError>

Execute a compiled vector-only search and return matching hits.

Phase 11 delivers the standalone vector retrieval path. The emitted SQL performs a vec0 KNN scan over vec_nodes_active, joins to chunks and nodes (active rows only), and pushes fusable filters into the candidate CTE. The outer SELECT applies residual JSON predicates and orders by score descending, where score = -distance (higher is better) per addendum 1 §Vector-Specific Behavior.

Capability-miss handling

If the sqlite-vec capability is absent (feature disabled or the vec_nodes_active virtual table has not been created because the engine was not opened with a vector_dimension), this method returns an empty SearchRows with was_degraded = true. This is non-fatal — the error does not propagate — matching the addendum’s §Vector-Specific Behavior / Degradation.

Attribution

When compiled.attribution_requested == true, every returned hit carries attribution: Some(HitAttribution { matched_paths: vec![] }) per addendum 1 §Attribution on vector hits (Phase 5 chunk-hit rule extended uniformly).

Errors

Returns EngineError if the SQL statement cannot be prepared or executed for reasons other than a vec-table capability miss.

pub fn execute_retrieval_plan( &self, plan: &CompiledRetrievalPlan, raw_query: &str, ) -> Result<SearchRows, EngineError>

Execute a unified CompiledRetrievalPlan (Phase 12 search() entry point) and return deterministically ranked, block-ordered SearchRows.

Stages, per addendum 1 §Retrieval Planner Model:

1. Text strict. Always runs (empty query short-circuits to an empty branch result inside run_search_branch).
2. Text relaxed. Runs iff the plan carries a relaxed branch AND the strict branch returned fewer than min(FALLBACK_TRIGGER_K, limit) hits — same v1 (K = 1) zero-hits-only trigger as the Phase 6 text-only path.
3. Vector. Runs iff text retrieval (strict + relaxed combined) returned zero hits AND plan.vector is Some. In v1 the planner never wires a vector branch through search(), so this code path is structurally present but dormant. A future phase that wires read-time embedding into compile_retrieval_plan will immediately light it up.
4. Fusion. All collected hits are merged via [merge_search_branches_three], which produces strict -> relaxed -> vector block ordering with cross-branch dedup resolved by branch precedence.

was_degraded covers only the relaxed-branch cap miss in v1. The addendum’s “vector capability miss => was_degraded” semantics applies to search() only when the unified planner actually fires the vector branch, which v1 never does.

Errors

Returns EngineError if any stage’s SQL cannot be prepared or executed for a non-capability-miss reason.

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.