Struct HyphaeEngine 

pub struct HyphaeEngine { /* private fields */ }

Embeddable autonomous Hyphae engine.

Implementations

impl HyphaeEngine

pub fn open(path: impl AsRef<Path>) -> Result<OpenedEngine, EngineError>

Opens one exclusively owned data directory and completes recovery.

Errors

Returns an error for directory contention, corruption, unsupported formats, snapshot mismatch, or failed index replay.

pub fn open_with_limits( path: impl AsRef<Path>, limits: StorageLimits, ) -> Result<OpenedEngine, EngineError>

Opens one data directory under explicit finite recovery and maintenance limits.

Errors

Returns an error for invalid limits, contention, corruption, exhausted recovery policy, timeout, unsupported formats, or failed replay.

pub fn data_path(&self) -> &Path

Returns the owned data-directory path.

pub fn put_record( &mut self, transaction_id: Uuid, record: &Record, ) -> Result<AppendOutcome, EngineError>

Atomically stores one canonical structured record.

Errors

Returns a document codec or durable storage error.

pub fn put_records( &mut self, transaction_id: Uuid, records: &[Record], ) -> Result<AppendOutcome, EngineError>

Atomically stores a batch of canonical structured records.

Encoding every document and checking duplicate keys happens before the log append, so a codec failure cannot partially commit the batch.

Errors

Returns an error for duplicate batch keys, document bounds, key bounds, idempotency conflicts, or durable storage failures.

pub fn delete_record( &mut self, transaction_id: Uuid, key: &[u8], ) -> Result<AppendOutcome, EngineError>

Atomically deletes one structured record.

Errors

Returns a key-validation, idempotency, or durable storage error.

pub fn delete_records( &mut self, transaction_id: Uuid, keys: &[&[u8]], ) -> Result<AppendOutcome, EngineError>

Atomically deletes a batch of structured records.

Duplicate keys are rejected before the log append. Deleting a missing key remains a successful durable operation.

Errors

Returns an error for duplicate keys, invalid key bounds, idempotency conflicts, or durable storage failures.

pub fn get_record(&self, key: &[u8]) -> Result<Option<Record>, EngineError>

Gets and verifies one structured record by binary key.

Errors

Returns a key, storage, or canonical document verification error.

pub fn get_record_with_proof( &self, key: &[u8], ) -> Result<ResultProofArtifact, EngineError>

Gets one structured record and binds the complete result, including absence, to a canonical snapshot witness.

Errors

Returns a key, storage, document, snapshot, or result-proof error.

pub fn get_record_with_proof_with_limits( &self, key: &[u8], maintenance: &MaintenanceLimits, ) -> Result<ResultProofArtifact, EngineError>

Gets one record and creates its witness under explicit maintenance limits.

Errors

Returns a key, storage, document, snapshot-limit, timeout, or result-proof error.

pub fn query( &self, query: &Query, limits: &ExecutionLimits, ) -> Result<QueryResult, EngineError>

Executes deterministic structured query over all durable documents.

Storage scan and document decoding consume the same wall-clock timeout; the reference executor receives only the remaining duration.

Errors

Returns a storage, document, query validation, global budget, aggregate, or timeout error. No partial page is returned.

pub fn query_with_byte_limit( &self, query: &Query, limits: &ExecutionLimits, max_scanned_bytes: u64, ) -> Result<QueryResult, BoundedEngineQueryError>

Executes deterministic structured query under an explicit aggregate durable key/document byte budget.

The budget is enforced inside each storage page before its key/value bytes are cloned and again by the reference executor. Existing Legacy Self::query callers retain the 0.2.0 count-bounded behavior.

Errors

Returns a storage, document, query validation, global count/byte budget, aggregate, or timeout error. No partial page is returned.

pub fn query_with_proof( &self, query: &Query, limits: &ExecutionLimits, ) -> Result<ResultProofArtifact, EngineError>

Executes one structured query and binds its complete logical result to a canonical snapshot witness at the same locked checkpoint.

Errors

Returns any ordinary query error plus snapshot or proof creation failures. No proof is returned for a partial or failed query.

pub fn query_with_proof_with_limits( &self, query: &Query, limits: &ExecutionLimits, max_scanned_bytes: u64, maintenance: &MaintenanceLimits, ) -> Result<ResultProofArtifact, BoundedEngineQueryError>

Executes one query and creates its witness under the query’s remaining end-to-end timeout and explicit maintenance bounds.

Errors

Returns any ordinary query error plus snapshot-limit, timeout, or proof-creation failures.

pub fn retrieve_vectors( shards: &[&[VectorRecord]], request: &RetrievalRequest, limits: &RetrievalLimits, ) -> Result<RetrievalOutcome, EngineError>

Executes exact provider-neutral vector retrieval without persisting or producing embeddings.

Errors

Returns vector, shape, duplicate-key, budget, or timeout errors.

pub fn define_vector_space( &mut self, transaction_id: Uuid, definition: VectorSpaceDefinition, ) -> Result<AppendOutcome, EngineError>

Defines one immutable durable named vector space.

Repeating the identical definition is idempotent; changing dimension or metric for an existing name fails before the log append.

Errors

Returns an idempotency, immutable-definition, or durable storage error.

pub fn put_vectors( &mut self, transaction_id: Uuid, space: &VectorSpaceName, vectors: &[(Vec<u8>, Q15Vector)], ) -> Result<AppendOutcome, EngineError>

Atomically stores vectors in one named space.

Errors

Returns an error before append for duplicate keys, an unknown space, wrong dimensions, invalid keys, or invalid vectors.

pub fn delete_vectors( &mut self, transaction_id: Uuid, space: &VectorSpaceName, keys: &[&[u8]], ) -> Result<AppendOutcome, EngineError>

Atomically deletes vectors from one named space.

Errors

Returns an error before append for duplicate/invalid keys or an unknown vector space.

pub fn retrieve_exact( &self, request: &ExactRetrievalRequest, limits: &ExactRetrievalLimits, ) -> Result<ExactRetrievalOutcome, EngineError>

Executes exact retrieval over the latest caught-up durable vector state. Storage budgets are enforced before returning candidates, then the canonical executor applies scoring and timeout policy.

Errors

Returns an error for an unknown space, wrong query dimension, exhausted budget, timeout, stale storage, or malformed durable state. No partial ranking is returned.

pub fn retrieve_exact_with_proof( &self, request: &ExactRetrievalRequest, limits: &ExactRetrievalLimits, ) -> Result<ExactRetrievalProofArtifact, EngineError>

Executes exact durable retrieval and binds its complete outcome to a canonical format-2 snapshot witness.

Errors

Returns any exact-retrieval, snapshot, or retrieval-proof error. No proof is emitted for failed or partial execution.

pub fn retrieve_exact_with_proof_with_limits( &self, request: &ExactRetrievalRequest, limits: &ExactRetrievalLimits, maintenance: &MaintenanceLimits, ) -> Result<ExactRetrievalProofArtifact, EngineError>

Executes exact retrieval and creates its witness under the retrieval operation’s remaining end-to-end timeout and explicit maintenance bounds.

Errors

Returns any exact-retrieval error plus snapshot-limit, timeout, or proof-creation failures.

pub fn define_lexical_index( &mut self, transaction_id: Uuid, definition: LexicalIndexDefinition, ) -> Result<AppendOutcome, EngineError>

Defines one immutable provider-free lexical index.

Repeating the identical definition is idempotent. Any change to an existing definition fails before the durable append.

Errors

Returns an immutable-definition, idempotency, or storage error.

pub fn retrieve_lexical( &self, request: &LexicalRequest, limits: &LexicalLimits, ) -> Result<LexicalOutcome, EngineError>

Executes provider-free lexical retrieval from the rebuildable durable posting projection.

Posting lookup, candidate materialization, and reference scoring share one lexical timeout and never return a partial ranking.

Errors

Returns an unknown-index, document, budget, timeout, or storage error.

pub fn retrieve_lexical_with_proof( &self, request: &LexicalRequest, limits: &LexicalLimits, ) -> Result<LexicalRetrievalProofArtifact, EngineError>

Executes lexical retrieval and binds the complete outcome to a canonical format-2 snapshot witness.

Errors

Returns any lexical, snapshot, or retrieval-proof error.

pub fn retrieve_lexical_with_proof_with_limits( &self, request: &LexicalRequest, limits: &LexicalLimits, maintenance: &MaintenanceLimits, ) -> Result<LexicalRetrievalProofArtifact, EngineError>

Executes lexical retrieval and creates its witness under the retrieval operation’s remaining timeout and explicit maintenance bounds.

Errors

Returns any lexical error plus snapshot-limit, timeout, or proof-creation failures.

pub fn retrieve_hybrid( &self, lexical_request: &LexicalRequest, lexical_limits: &LexicalLimits, vector_request: &ExactRetrievalRequest, vector_limits: &ExactRetrievalLimits, hybrid_request: &HybridRequest, ) -> Result<HybridOutcome, EngineError>

Executes both durable branches and fuses their complete outcomes using deterministic RRF semantics.

Errors

Returns any lexical, exact-vector, storage, budget, timeout, or fusion error. Branch failures never silently downgrade to single-modality success.

pub fn retrieve_hybrid_with_proof( &self, lexical_request: &LexicalRequest, lexical_limits: &LexicalLimits, vector_request: &ExactRetrievalRequest, vector_limits: &ExactRetrievalLimits, hybrid_request: &HybridRequest, ) -> Result<HybridRetrievalProofArtifact, EngineError>

Executes lexical and exact-vector branches, fuses their complete outcomes, and binds all three outcomes to one canonical snapshot.

Errors

Returns any branch, fusion, snapshot, or retrieval-proof error.

pub fn retrieve_hybrid_with_proof_with_limits( &self, lexical_request: &LexicalRequest, lexical_limits: &LexicalLimits, vector_request: &ExactRetrievalRequest, vector_limits: &ExactRetrievalLimits, hybrid_request: &HybridRequest, maintenance: &MaintenanceLimits, ) -> Result<HybridRetrievalProofArtifact, EngineError>

Executes both hybrid branches and creates their shared witness under one combined remaining branch timeout and explicit maintenance bounds.

Errors

Returns any branch, fusion, snapshot-limit, timeout, or proof error.

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

Creates or reuses a verified logical snapshot.

Errors

Returns a stale-handle, index, or snapshot error.

pub fn snapshot_with_limits( &self, limits: &MaintenanceLimits, ) -> Result<SnapshotInfo, EngineError>

Creates or reuses a verified logical snapshot under explicit limits.

Errors

Returns a limit, timeout, stale-handle, index, or snapshot error.

pub fn compact(&mut self) -> Result<CompactionOutcome, EngineError>

Commits an anchored compaction generation.

Errors

Returns a stale-handle, snapshot, segment, or manifest error.

pub fn compact_with_limits( &mut self, limits: &MaintenanceLimits, ) -> Result<CompactionOutcome, EngineError>

Commits an anchored compaction generation under one finite deadline.

Errors

Returns a limit, timeout, stale-handle, snapshot, segment, or manifest error before the manifest commit point.

pub fn backup( &self, destination: impl AsRef<Path>, ) -> Result<BackupInfo, EngineError>

Creates an atomic portable backup at the locked logical checkpoint.

Errors

Returns a snapshot, destination, synchronization, or promotion error.

pub fn verify_backup(path: impl AsRef<Path>) -> Result<BackupInfo, EngineError>

Verifies a portable backup without opening a live data directory.

Errors

Returns an error for a malformed layout, metadata mismatch, or corrupt snapshot.

pub fn restore_backup( backup: impl AsRef<Path>, destination: impl AsRef<Path>, ) -> Result<RestoreInfo, EngineError>

Restores a backup to a new atomically activated data directory.

Errors

Returns an error before destination activation if verification, index reconstruction, reopen, or filesystem synchronization fails.

Trait Implementations

impl Debug for HyphaeEngine

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

Formats the value using the given formatter.