Struct Engine 

pub struct Engine { /* private fields */ }

Implementations

impl Engine

pub fn open(path: impl Into<PathBuf>) -> Result<OpenedEngine, EngineOpenError>

pub fn open_with_choice( path: impl Into<PathBuf>, choice: EmbedderChoice, ) -> Result<OpenedEngine, EngineOpenError>

Open an engine with an explicit EmbedderChoice.

Per dev/design/embedder.md §0 + the 0.7.1 EU-5 campaign, this is the canonical entry point for selecting how the workspace’s default embedder is supplied. See EmbedderChoice for the semantics of each variant; in particular Default materializes the pinned BGE embedder via the loader when the default-embedder feature is enabled.

pub fn open_with_migration_event_sink( path: impl Into<PathBuf>, emit_migration_event: impl FnMut(&MigrationStepReport), ) -> Result<OpenedEngine, EngineOpenError>

pub fn path(&self) -> &Path

pub fn write( &self, batch: &[PreparedWrite], ) -> Result<WriteReceipt, EngineError>

pub fn search(&self, query: &str) -> Result<SearchResult, EngineError>

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

pub fn drain(&self, timeout_ms: u64) -> Result<(), EngineError>

Block until in-flight writes drain or timeout_ms elapses.

Surface owned by dev/interfaces/rust.md § Engine-attached instrumentation; semantics are owned by dev/design/lifecycle.md.

pub fn counters(&self) -> CounterSnapshot

Snapshot of engine-internal counters.

Field set owned by dev/design/lifecycle.md.

pub fn set_profiling(&self, enabled: bool) -> Result<(), EngineError>

Toggle response-cycle profiling.

Per dev/design/lifecycle.md § Per-statement profiling, profiling is an opt-in surface that is independently toggleable on a running engine without restart. AC-005a locks runtime toggleability.

pub fn set_slow_threshold_ms(&self, value: u64) -> Result<(), EngineError>

Set the threshold above which an operation is reported as slow.

Per dev/design/lifecycle.md § Slow and heartbeat policy, the threshold is runtime-configurable; mutating it changes detection behavior on subsequent statements without restart (AC-007b).

pub fn subscribe(&self, subscriber: Arc<dyn Subscriber>) -> Subscription

Attach a host subscriber to engine events.

Dropping the returned Subscription detaches the subscriber. Payload shape owned by dev/design/lifecycle.md and dev/design/migrations.md.

pub fn drain_embedder_events(&self) -> Result<Vec<EmbedderEvent>, EngineError>

0.7.2 PR-2b — NON-test observation seam. Drains and returns every EmbedderEvent queued since the last drain (mean pin, manual mean recompute). Production callers use this to observe the synchronous recompute work; events are queued only AFTER the recompute transaction is durable, so a rolled-back recompute never surfaces. Mirrors the at-open OpenReport.embedder_events channel for the steady-state path.

pub fn recompute_mean(&self) -> Result<MeanRecomputeReport, EngineError>

0.7.2 PR-2b — explicit doctor recompute-mean path. Re-derives the pinned corpus mean from the current vector_default rows and re-quantizes every row, SYNCHRONOUSLY in one transaction. ALWAYS allowed at any corpus size — this is the ONLY mean-refresh path as of 0.7.2 (the automatic in-ingest drift detector was carved out / deferred to 0.8.x; see dev/design/embedder.md §0.3).

Serializes against the projection workers via commit_gate so the re-quantize sees a totally-ordered history, exactly like the at-pin commit. Publishes a MeanVecRecomputed { trigger: Manual } event only after the transaction is durable. No-op-safe on a non-MC identity (returns EmbedderNotConfigured rather than corrupting an un-centered workspace).

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

Doctor read-only integrity report. Three-section output per AC-043a/b. opts.full adds PRAGMA integrity_check. quick and round_trip are accepted but treated as default for 0.6.0.

pub fn safe_export( &self, out: &Path, manifest: &Path, ) -> Result<SafeExportArtifact, EngineError>

Doctor bit-preserving export. Runs VACUUM INTO to produce a self-contained SQLite file at out, computes SHA-256 of the resulting bytes, and writes a JSON manifest at manifest. Per AC-039a/b.

pub fn rebuild_projections(&self) -> Result<RebuildReport, EngineError>

Operator regenerate workflow per dev/design/projections.md § Regenerate workflow. Drains in-flight projection work, then truncates FTS5 + vec0 shadow rows, resets the projection cursor, and lets the scheduler re-enqueue every canonical row. Durable projection_failures audit rows are preserved per design. AC-044

• AC-063c.

pub fn rebuild_vec0(&self) -> Result<RebuildReport, EngineError>

Vec0-only variant of Engine::rebuild_projections. Leaves FTS5 shadow content untouched; per recovery design, recover --rebuild-vec0 is the surface for vec0-only repair.

pub fn trace_source_ref( &self, source_id: &str, ) -> Result<TraceReport, EngineError>

Phase 9 Pack B / AC-042 source trace. Returns the canonical-row id set produced by source_id, ordered by write_cursor. Empty string is not a valid source_id; rows with NULL source_id are excluded from every result.

pub fn excise_source( &self, source_id: &str, ) -> Result<ExciseReport, EngineError>

Phase 9 Pack B / AC-028a/b/c source excise. Drains in-flight projection work, then deletes every canonical row attributable to source_id plus the FTS5 + vec0 shadow rows that referenced those cursors, and appends an audit row to the excise_source_audit operational collection.

Non-perturbation: rows from other sources (and rows with NULL source_id) are untouched; the projection cursor is NOT reset and no blanket projection rebuild is issued.

pub fn verify_embedder( &self, supplied_identity: &str, supplied_dimension: u32, ) -> Result<VerifyEmbedderReport, EngineError>

Doctor verify-embedder seam (AC-040a). Compares the _fathomdb_embedder_profiles row to the operator-supplied name:revision identity + dimension; never raises on mismatch.

pub fn dump_schema(&self) -> Result<DumpSchemaReport, EngineError>

Doctor dump-schema seam (AC-040a). Returns the PRAGMA user_version sentinel plus the table + index inventory from sqlite_schema, excluding sqlite_* internal rows. Canonical tables appear first per CANONICAL_TABLES.

pub fn dump_row_counts(&self) -> Result<DumpRowCountsReport, EngineError>

Doctor dump-row-counts seam (AC-040a). Emits canonical-table counts only; projection / FTS / vec0 shadow tables are excluded.

pub fn dump_profile(&self) -> Result<DumpProfileReport, EngineError>

Doctor dump-profile seam (AC-040a). Returns the stored embedder identity + dimension plus the registered vectorized kinds from _fathomdb_vector_kinds.

pub fn truncate_wal(&self) -> Result<TruncateWalReport, EngineError>

Recover --truncate-wal seam. Runs PRAGMA wal_checkpoint(TRUNCATE) and returns the three counters SQLite reports. status = Busy when SQLite signalled a blocked checkpoint (busy != 0); the WAL may still be partially checkpointed in that case.

Trait Implementations

impl Debug for Engine

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

Formats the value using the given formatter.

impl Drop for Engine

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.