Frankensearch

https://docs.rs/frankensearch/0.3.2/frankensearch/
Admin
Frankensearch is a two-tier hybrid search library for Rust that combines lexical BM25 and semantic...
Tokens:55,286
Snippets:708
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Handling Search Phases

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/enum.SearchPhase.html

Example of iterating through search phases and matching on each variant to update the UI or handle errors.

```rust
for phase in searcher.search("distributed consensus", 10) {
    match phase {
        SearchPhase::Initial { results, .. } => display_immediately(&results),
        SearchPhase::Refined { results, .. } => update_display(&results),
        SearchPhase::Reranked { results, .. } => update_display_with_final_scores(&results),
        SearchPhase::RefinementFailed { initial_results, error, .. } => {
            // Keep showing initial results, log the error
            log_warning(&error);
        }
    }
}
```

--------------------------------

### Implementing and Adapting SyncEmbed

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/trait.SyncEmbed.html

Example showing how to implement the SyncEmbed trait for a custom struct and wrap it with SyncEmbedderAdapter for async compatibility.

```rust
use frankensearch_core::traits::{SyncEmbed, SyncEmbedderAdapter, Embedder};

struct MyHashEmbedder { dim: usize }

impl SyncEmbed for MyHashEmbedder {
    fn embed_sync(&self, text: &str) -> SearchResult<Vec<f32>> { /* ... */ }
    fn dimension(&self) -> usize { self.dim }
    fn id(&self) -> &str { "my-hash" }
    fn model_name(&self) -> &str { "My Hash Embedder" }
    fn is_semantic(&self) -> bool { false }
    fn category(&self) -> ModelCategory { ModelCategory::HashEmbedder }
}

// Use it as a full async Embedder:
let adapted: Box<dyn Embedder> = Box::new(SyncEmbedderAdapter(MyHashEmbedder { dim: 256 }));
```

--------------------------------

### Result::cloned Implementation

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/type.SearchResult.html

Examples of cloning the contents of an Ok variant for both shared and mutable references.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### Result::copied Implementation

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/type.SearchResult.html

Examples of copying the contents of an Ok variant for both shared and mutable references.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### Result::flatten Implementation

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/type.SearchResult.html

Examples of flattening nested Result types.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

--------------------------------

### Result::transpose Implementation

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/type.SearchResult.html

Example of transposing a Result of an Option into an Option of a Result.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

--------------------------------

### task_type

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Gets or sets the task type label.

```APIDOC
## pub fn task_type(&self) -> Option<String>

### Description
Returns the task type label, if one has been set.

## pub fn set_task_type(&self, task_type: impl Into<String>)

### Description
Sets a task type label for adaptive monitoring and metrics.
```

--------------------------------

### Retrieve full cancellation reason

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Get the full cancellation reason including attribution using cancel_reason.

```rust
use asupersync::{Cx, types::CancelKind};

let cx = Cx::for_testing();
assert!(cx.cancel_reason().is_none());

cx.cancel_with(CancelKind::Timeout, Some("request timeout"));
if let Some(reason) = cx.cancel_reason() {
    assert_eq!(reason.kind, CancelKind::Timeout);
    println!("Cancelled: {:?}", reason.kind);
}
```

--------------------------------

### Get mutable reference to Arc

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SharedMetricsExporter.html

Retrieves a mutable reference if no other pointers exist. Returns None if other references are present.

```rust
use std::sync::Arc;

let mut x = Arc::new(3);
*Arc::get_mut(&mut x).unwrap() = 4;
assert_eq!(*x, 4);

let _y = Arc::clone(&x);
assert!(Arc::get_mut(&mut x).is_none());
```

--------------------------------

### Get strong reference count

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SharedMetricsExporter.html

Retrieves the number of strong Arc pointers to an allocation. The result is subject to change if the Arc is shared across threads.

```rust
use std::sync::Arc;

let five = Arc::new(5);
let _also_five = Arc::clone(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` between threads.
assert_eq!(2, Arc::strong_count(&five));
```

--------------------------------

### Get Weak pointer count

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SharedMetricsExporter.html

Retrieves the number of Weak pointers associated with an Arc allocation. Note that this count can change concurrently in multi-threaded contexts.

```rust
use std::sync::Arc;

let five = Arc::new(5);
let _weak_five = Arc::downgrade(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` or `Weak` between threads.
assert_eq!(1, Arc::weak_count(&five));
```

--------------------------------

### Create a scope from context

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Demonstrates both the recommended scope! macro and manual scope creation for task spawning.

```rust
// Using the scope! macro (recommended):
scope!(cx, {
    let handle = scope.spawn(|cx| async { 42 });
    handle.await
});

// Manual scope creation:
let scope = cx.scope();
// Use scope for spawning...
```

--------------------------------

### Create Testing Context with I/O

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Initializes a Cx instance with lab I/O capabilities for testing I/O paths.

```rust
use asupersync::Cx;

let cx = Cx::for_testing_with_io();
assert!(cx.has_io());
assert!(!cx.io().unwrap().is_real_io());
```

--------------------------------

### Initialize and execute a TwoTierSearcher

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.TwoTierSearcher.html

Demonstrates the fluent configuration pattern and the asynchronous search execution with a callback for handling different search phases.

```rust
let searcher = TwoTierSearcher::new(index, fast_embedder, config)
    .with_quality_embedder(quality)
    .with_lexical(tantivy)
    .with_reranker(reranker);

let metrics = searcher.search(&cx, "distributed consensus", 10, text_fn, |phase| {
    match phase {
        SearchPhase::Initial { results, .. } => display(&results),
        SearchPhase::Refined { results, .. } => update_display(&results),
        SearchPhase::RefinementFailed { .. } => { /* keep initial */ }
    }
}).await?;
```

--------------------------------

### Get root cancellation cause

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Retrieve the original trigger of a cancellation using root_cancel_cause.

```rust
use asupersync::{Cx, types::{CancelKind, CancelReason}};

let cx = Cx::for_testing();

// Simulate a deep cancellation chain
let deadline = CancelReason::deadline();
let parent1 = CancelReason::parent_cancelled().with_cause(deadline);
let parent2 = CancelReason::parent_cancelled().with_cause(parent1);

cx.set_cancel_reason(parent2);

// Root cause is the original Deadline, not ParentCancelled
if let Some(root) = cx.root_cancel_cause() {
    assert_eq!(root.kind, CancelKind::Deadline);
}
```

--------------------------------

### Create Testing Context with Budget

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Initializes a Cx instance for testing with a specific deadline budget.

```rust
use asupersync::{Cx, Budget, Time};

// Create a context with a 30-second deadline
let cx = Cx::for_testing_with_budget(
    Budget::new().with_deadline(Time::from_secs(30))
);
```

--------------------------------

### Using the I/O Capability

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Demonstrates checking for and using the I/O capability within an async function.

```rust
async fn read_data(cx: &Cx) -> io::Result<Vec<u8>> {
    let io = cx.io().ok_or_else(|| {
        io::Error::new(io::ErrorKind::Unsupported, "I/O not available")
    })?;

    // Use io capability...
    Ok(vec![])
}
```

--------------------------------

### open

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.VectorIndex.html

Opens an existing FSVI index from disk.

```APIDOC
## open

### Description
Opens an existing FSVI index from the specified file path.

### Signature
`pub fn open(path: &Path) -> Result<VectorIndex, SearchError>`
```

--------------------------------

### Configuration Methods

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.TwoTierSearcher.html

Fluent builder methods to configure the searcher pipeline.

```APIDOC
## Configuration Methods

### Description
These methods allow for chaining configuration options to the TwoTierSearcher instance.

- **with_quality_embedder(embedder: Arc<dyn Embedder>)**: Sets the quality-tier embedder.
- **with_lexical(lexical: Arc<dyn LexicalSearch>)**: Sets the lexical search backend.
- **with_reranker(reranker: Arc<dyn Reranker>)**: Sets the cross-encoder reranker.
- **with_embedding_cache(capacity: usize)**: Enables a query embedding cache with a specified capacity.
```

--------------------------------

### Build and search a two-tier index

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/index.html

Demonstrates initializing an index with an embedder stack and performing a two-tier search. Requires the default 'hash' feature.

```rust
use std::sync::Arc;
use frankensearch::prelude::*;
use frankensearch::{EmbedderStack, HashEmbedder, IndexBuilder, TwoTierIndex};
use frankensearch_core::traits::Embedder;

asupersync::test_utils::run_test_with_cx(|cx| async move {
    // Build an index
    let fast = Arc::new(HashEmbedder::default_256()) as Arc<dyn Embedder>;
    let quality = Arc::new(HashEmbedder::default_384()) as Arc<dyn Embedder>;
    let stack = EmbedderStack::from_parts(fast, Some(quality));

    let stats = IndexBuilder::new("./my_index")
        .with_embedder_stack(stack)
        .add_document("doc-1", "Rust ownership and borrowing")
        .add_document("doc-2", "Python garbage collection")
        .build(&cx)
        .await
        .expect("build index");

    // Search
    let fast = Arc::new(HashEmbedder::default_256()) as Arc<dyn Embedder>;
    let index = Arc::new(TwoTierIndex::open("./my_index", TwoTierConfig::default()).unwrap());
    let searcher = TwoTierSearcher::new(index, fast, TwoTierConfig::default());
    let (results, metrics) = searcher
        .search_collect(&cx, "memory management", 10)
        .await
        .expect("search");

    for result in &results {
        println!("{}: {:.4}", result.doc_id, result.score);
    }
});
```

--------------------------------

### Create Testing Context

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Initializes a Cx instance for unit and integration testing with default settings.

```rust
use asupersync::Cx;

let cx = Cx::for_testing();
assert!(!cx.is_cancel_requested());
assert!(cx.checkpoint().is_ok());
```

--------------------------------

### for_testing

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Creates a capability context for testing purposes with default IDs and an infinite budget.

```APIDOC
## pub fn for_testing() -> Cx

### Description
Creates a capability context for testing purposes. This constructor creates a Cx with default IDs and an infinite budget, suitable for unit and integration tests.
```

--------------------------------

### pub fn as_ref(&self) -> Pin<&<Ptr as Deref>::Target>

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SearchFuture.html

Gets a shared reference to the pinned value this Pin points to.

```APIDOC
## pub fn as_ref(&self) -> Pin<&<Ptr as Deref>::Target>

### Description
Gets a shared reference to the pinned value this `Pin` points to. This is a safe way to go from `&Pin<Pointer<T>>` to `Pin<&T>`.
```

--------------------------------

### for_request

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Creates a request-scoped capability context with an infinite budget.

```APIDOC
## pub fn for_request() -> Cx

### Description
Creates a request-scoped capability context with an infinite budget.
```

--------------------------------

### pub fn as_mut(&mut self) -> Pin<&mut <Ptr as Deref>::Target>

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SearchFuture.html

Gets a mutable reference to the pinned value this Pin points to.

```APIDOC
## pub fn as_mut(&mut self) -> Pin<&mut <Ptr as Deref>::Target>

### Description
Gets a mutable reference to the pinned value this `Pin<Ptr>` points to. This is useful when performing multiple calls to functions that consume the pinning pointer.
```

--------------------------------

### for_testing_with_io

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Creates a test-only capability context with lab I/O capability.

```APIDOC
## pub fn for_testing_with_io() -> Cx

### Description
Creates a test-only capability context with a LabIoCap for testing I/O code paths without performing real I/O.
```

--------------------------------

### pub fn as_deref_mut(self: Pin<&mut Pin<Ptr>>) -> Pin<&mut <Ptr as Deref>::Target>

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SearchFuture.html

Gets Pin<&mut T> to the underlying pinned value from a nested Pin-pointer.

```APIDOC
## pub fn as_deref_mut(self: Pin<&mut Pin<Ptr>>) -> Pin<&mut <Ptr as Deref>::Target>

### Description
Gets `Pin<&mut T>` to the underlying pinned value from this nested `Pin`-pointer. This is a safe conversion from `Pin<&mut Pin<Pointer<T>>>` to `Pin<&mut T>`.
```

--------------------------------

### Scope with Budget

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Demonstrates using the scope! macro with a custom budget.

```rust
scope!(cx, budget: Budget::with_deadline_secs(5), {
    // body
})
```

--------------------------------

### Chain fallible operations with and_then

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/type.SearchResult.html

Use and_then to chain operations that return a Result. The provided examples demonstrate handling successful values, overflow errors, and propagating existing errors.

```rust
assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));
assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));
assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));
```

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### for_request_with_budget

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Creates a request-scoped capability context with a specified budget.

```APIDOC
## pub fn for_request_with_budget(budget: Budget) -> Cx

### Description
Creates a request-scoped capability context with a specified budget. This is intended for production request handling that needs unique task/region identifiers outside the scheduler.
```

--------------------------------

### for_testing_with_budget

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Creates a test-only capability context with a specified budget.

```APIDOC
## pub fn for_testing_with_budget(budget: Budget) -> Cx

### Description
Creates a test-only capability context with a specified budget. This allows specifying a custom budget for testing timeout behavior.
```

--------------------------------

### TwoTierSearcher Configuration Methods

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.TwoTierSearcher.html

Fluent configuration methods for the TwoTierSearcher.

```APIDOC
## Configuration Methods

- **with_quality_embedder(embedder: Arc<dyn Embedder>)** - Sets the quality-tier embedder for progressive refinement.
- **with_lexical(lexical: Arc<dyn LexicalSearch>)** - Sets the lexical search backend for hybrid RRF fusion.
- **with_reranker(reranker: Arc<dyn Reranker>)** - Sets the cross-encoder reranker for Phase 2.
- **with_embedding_cache(capacity: usize)** - Wraps embedders with a query embedding cache.
```

--------------------------------

### Importing the frankensearch prelude

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/index.html

Use this import to bring common types and traits into scope for easier access.

```rust
use frankensearch::prelude::*;
```

--------------------------------

### SyncTwoTierSearcher::new

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.SyncTwoTierSearcher.html

Creates a new instance of the SyncTwoTierSearcher using an in-memory two-tier index and configuration.

```APIDOC
## SyncTwoTierSearcher::new

### Description
Initializes a new synchronous searcher backed by an `InMemoryTwoTierIndex`.

### Signature
`pub const fn new(index: Arc<InMemoryTwoTierIndex>, config: TwoTierConfig) -> SyncTwoTierSearcher`
```

--------------------------------

### Report progress with checkpoint_with

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Record a human-readable progress message while checking for cancellation.

```rust
async fn process_batch(cx: &Cx, items: &[Item]) -> Result<(), Error> {
    for (i, item) in items.iter().enumerate() {
        cx.checkpoint_with(format!("Processing item {}/{}", i + 1, items.len()))?;
        process(item).await?;
    }
    Ok(())
}
```

--------------------------------

### IndexBuilder Methods

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.IndexBuilder.html

Methods for configuring and executing the index build process.

```APIDOC
## IndexBuilder

### Description
Fluent builder for creating frankensearch indexes. Handles embedder auto-detection, vector index creation, batch embedding, and error aggregation.

### Methods

- **new(data_dir: impl Into<PathBuf>) -> Self**: Create a new builder targeting the given directory.
- **with_config(self, config: TwoTierConfig) -> Self**: Override the search/index configuration.
- **with_embedder_stack(self, stack: EmbedderStack) -> Self**: Use a specific embedder stack instead of auto-detecting.
- **with_batch_size(self, batch_size: usize) -> Self**: Set the batch size for embedding operations (Default: 32).
- **with_progress(self, callback: impl FnMut(IndexProgress) + Send + 'static) -> Self**: Set a progress callback.
- **add_document(self, id: impl Into<String>, content: impl Into<String>) -> Self**: Add a single document to be indexed.
- **add_document_with_title(self, id: impl Into<String>, content: impl Into<String>, title: impl Into<String>) -> Self**: Add a document with title.
- **add_documents(self, docs: impl IntoIterator<Item = IndexableDocument>) -> Self**: Add multiple documents.
- **build(self, cx: &Cx) -> SearchResult<IndexBuildStats>**: Build the index, embedding all documents and writing FSVI files.
```

--------------------------------

### Create and use a HashEmbedder

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.HashEmbedder.html

Initialize a default 384-dimensional HashEmbedder and generate an embedding vector for a string.

```rust
use frankensearch_embed::HashEmbedder;

let embedder = HashEmbedder::default_384();
let vec = embedder.embed_sync("hello world");
assert_eq!(vec.len(), 384);
```

--------------------------------

### Calculate Product of Result Items

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/type.SearchResult.html

Demonstrates using the product method on an iterator of Results, which short-circuits on the first Err encountered.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

--------------------------------

### finish

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.VectorIndexWriter.html

Persists the index to disk, including fsync of file and parent directory.

```APIDOC
## pub fn finish(self) -> Result<(), SearchError>

### Description
Persists the index to disk, including fsync of file and parent directory.

### Errors
- Returns `SearchError::InvalidConfig` for layout/encoding failures.
- Returns `SearchError::Io` for filesystem write/sync failures.
```

--------------------------------

### checkpoint_with

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Checks for cancellation and records a progress message.

```APIDOC
## pub fn checkpoint_with(&self, msg: impl Into<String>) -> Result<(), Error>

### Description
Checks for cancellation while recording a human-readable message describing the current progress. The message is stored in the checkpoint state.

### Parameters
- **msg** (impl Into<String>) - Required - A message describing the current progress.
```

--------------------------------

### TwoTierIndex::open

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.TwoTierIndex.html

Opens a two-tier index from a specified directory path.

```APIDOC
## TwoTierIndex::open

### Description
Opens a two-tier index from a directory. It looks for fast-tier files (vector.fast.idx or vector.idx) and an optional quality-tier file (vector.quality.idx).

### Parameters
- **dir** (&Path) - Required - The directory path containing the index files.
- **config** (TwoTierConfig) - Required - The configuration settings for the index.

### Returns
- Result<TwoTierIndex, SearchError> - Returns the opened index or a SearchError if the index is not found or corrupted.
```

--------------------------------

### TwoTierConfig Methods

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.TwoTierConfig.html

Methods available for configuring and validating the TwoTierConfig instance.

```APIDOC
## pub fn with_env_overrides(self) -> TwoTierConfig

### Description
Load overrides from environment variables. Only overrides fields for which environment variables are set. Invalid or out-of-range values are rejected with a warning log.

## pub fn optimized() -> TwoTierConfig

### Description
Load optimized parameters from `data/optimized_params.toml` at the workspace root. Falls back to `Default::default()` if the file does not exist or cannot be parsed.

## pub fn validate(&self) -> Result<(), SearchError>

### Description
Validates the configuration parameters to prevent degenerate behavior. Returns `SearchError::InvalidConfig` if any parameter is out of bounds.

## pub fn with_metrics_exporter(self, exporter: Arc<dyn MetricsExporter>) -> TwoTierConfig

### Description
Attach a telemetry exporter to the configuration.

## pub fn without_metrics_exporter(self) -> TwoTierConfig

### Description
Remove any telemetry exporter and skip export callbacks.

## pub fn metrics_exporter(&self) -> Option<&Arc<dyn MetricsExporter>>

### Description
Returns the configured telemetry exporter, if any.
```

--------------------------------

### verify_capability

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Verifies the attached capability token against a root key and verification context.

```APIDOC
## pub fn verify_capability(&self, root_key: &AuthKey, context: &VerificationContext) -> Result<(), VerificationError>

### Description
Verify the attached capability token against a root key and context. Checks the HMAC chain integrity and evaluates all caveat predicates.
```

--------------------------------

### Clone Arc from reference

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SharedMetricsExporter.html

Demonstrates the experimental clone_from_ref API for creating an Arc from a reference.

```rust
#![feature(clone_from_ref)]
use std::sync::Arc;

let hello: Arc<str> = Arc::clone_from_ref("hello");
```

--------------------------------

### Try clone Arc from reference

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SharedMetricsExporter.html

Demonstrates the experimental try_clone_from_ref API which handles allocation failures.

```rust
#![feature(clone_from_ref)]
#![feature(allocator_api)]
use std::sync::Arc;

let hello: Arc<str> = Arc::try_clone_from_ref("hello")?;
```

--------------------------------

### DaemonFallbackEmbedder Constructor

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.DaemonFallbackEmbedder.html

Initializes a new instance of the embedder with a daemon client, a fallback embedder, and retry configuration.

```rust
pub fn new( daemon: Arc<dyn DaemonClient>, fallback: Arc<dyn SyncEmbed>, config: DaemonRetryConfig, ) -> DaemonFallbackEmbedder
```

--------------------------------

### pub fn for_testing_with_remote(cap: RemoteCap) -> Cx

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.Cx.html

Creates a test-only capability context with a remote capability.

```APIDOC
## pub fn for_testing_with_remote(cap: RemoteCap) -> Cx

### Description
Creates a test-only capability context with a `RemoteCap` for testing remote task spawning without a real network transport.
```

--------------------------------

### Resource and Lifecycle Management

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.Cx.html

Methods for checking task budgets and cancellation status.

```APIDOC
## pub fn budget(&self) -> Budget

### Description
Returns the current budget, which defines resource limits including deadlines, poll quotas, and priority.

## pub fn is_cancel_requested(&self) -> bool

### Description
Returns true if a cancellation signal has been sent to this task. This is a non-blocking check for graceful shutdown.
```

--------------------------------

### FederatedSearcher::new

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.FederatedSearcher.html

Creates a new federated searcher instance with default configuration.

```APIDOC
## pub fn new() -> FederatedSearcher

### Description
Create a federated searcher with default config.
```

--------------------------------

### DaemonFallbackEmbedder::new

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.DaemonFallbackEmbedder.html

Creates a new instance of DaemonFallbackEmbedder with the provided daemon client, fallback embedder, and retry configuration.

```APIDOC
## pub fn new(daemon: Arc<dyn DaemonClient>, fallback: Arc<dyn SyncEmbed>, config: DaemonRetryConfig) -> DaemonFallbackEmbedder

### Description
Constructs a new DaemonFallbackEmbedder that manages the transition between a remote daemon and a local fallback embedder.

### Parameters
- **daemon** (Arc<dyn DaemonClient>) - Required - The client used to communicate with the embedding daemon.
- **fallback** (Arc<dyn SyncEmbed>) - Required - The local embedder used if the daemon is unavailable.
- **config** (DaemonRetryConfig) - Required - Configuration settings for retry logic when interacting with the daemon.
```

--------------------------------

### logical_time_methods

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Methods for managing logical time within the context.

```APIDOC
## Logical Time Methods

- `logical_now(&self) -> LogicalTime`: Returns the current logical time without ticking.
- `logical_tick(&self) -> LogicalTime`: Records a local logical event and returns the updated time.
- `logical_receive(&self, sender_time: &LogicalTime) -> LogicalTime`: Merges a received logical time and returns the updated time.
```

--------------------------------

### InMemoryTwoTierIndex::from_dir

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.InMemoryTwoTierIndex.html

Loads an InMemoryTwoTierIndex from a directory on the filesystem.

```APIDOC
## pub fn from_dir(dir: &Path) -> Result<InMemoryTwoTierIndex, SearchError>

### Description
Loads from an existing two-tier index directory, reading all data into memory. Looks for vector.fast.idx (required) and vector.quality.idx (optional).
```

--------------------------------

### TwoTierSearcher::new

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.TwoTierSearcher.html

Creates a new instance of the TwoTierSearcher with a required fast-tier embedder and configuration.

```APIDOC
## pub fn new(index: Arc<TwoTierIndex>, fast_embedder: Arc<dyn Embedder>, config: TwoTierConfig) -> TwoTierSearcher

### Description
Initializes a new searcher instance. This is the entry point for building a search pipeline.

### Parameters
- **index** (Arc<TwoTierIndex>) - The search index.
- **fast_embedder** (Arc<dyn Embedder>) - The embedder used for the fast-tier search.
- **config** (TwoTierConfig) - Configuration settings for the searcher.
```

--------------------------------

### Trace with fields in Cx

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Logs a trace-level message with structured key-value fields for queryable log entries.

```rust
cx.trace_with_fields("request handled", &[
    ("method", "GET"),
    ("path", "/api/users"),
    ("status", "200"),
]);
```

--------------------------------

### I/O Registration

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.Cx.html

Method to register I/O sources with the reactor.

```APIDOC
## pub fn register_io<S>(&self, source: &S, interest: Interest) -> Result<IoRegistration, Error>

### Description
Registers an I/O source with the reactor for the given interest. Returns an IoRegistration handle that automatically deregisters when dropped.

### Parameters
- **source** (S: Source) - Required - The I/O source to register.
- **interest** (Interest) - Required - The I/O operations to monitor (read, write, or both).
```

--------------------------------

### register_io

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Registers an I/O source with the reactor.

```APIDOC
## pub fn register_io<S>(&self, source: &S, interest: Interest) -> Result<IoRegistration, Error>

### Description
Registers a source (such as a socket or file descriptor) with the reactor so that the task can be woken when I/O operations are ready.

### Parameters
- **source** (S: Source) - Required - The I/O source to register.
- **interest** (Interest) - Required - The I/O operations to monitor for (read, write, or both).

### Returns
- **IoRegistration** - A handle that represents the active registration. When dropped, the registration is automatically deregistered.
```

--------------------------------

### TwoTierSearcher::new

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.TwoTierSearcher.html

Creates a new instance of the TwoTierSearcher with a fast-tier embedder.

```APIDOC
## pub fn new(index: Arc<TwoTierIndex>, fast_embedder: Arc<dyn Embedder>, config: TwoTierConfig) -> TwoTierSearcher

### Description
Initializes a new searcher instance with the required index, fast-tier embedder, and configuration.

### Parameters
- **index** (Arc<TwoTierIndex>) - Required - The search index.
- **fast_embedder** (Arc<dyn Embedder>) - Required - The embedder for the fast tier.
- **config** (TwoTierConfig) - Required - Configuration settings for the searcher.
```

--------------------------------

### Provide default values with unwrap_or

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/type.SearchResult.html

Returns the contained Ok value or a provided default. Arguments are evaluated eagerly.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### pub fn checkpoint_with(&self, msg: impl Into<String>) -> Result<(), Error>

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.Cx.html

Checks for cancellation with a progress message. This method records a human-readable message describing the current progress.

```APIDOC
## pub fn checkpoint_with(&self, msg: impl Into<String>) -> Result<(), Error>

### Description
Checks for cancellation with a progress message. This is like `checkpoint()` but also records a human-readable message describing the current progress, which can be retrieved via `checkpoint_state()`.

### Parameters
- **msg** (impl Into<String>) - Required - A human-readable message describing the current progress.
```

--------------------------------

### DaemonRetryConfig::from_env

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.DaemonRetryConfig.html

Loads the retry configuration from environment variables, falling back to default values if variables are not set.

```APIDOC
## pub fn from_env() -> DaemonRetryConfig

### Description
Loads retry configuration from environment variables; falls back to defaults if environment variables are missing.

### Returns
- **DaemonRetryConfig** - The initialized configuration object.
```

--------------------------------

### quality_comparison

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/fn.quality_comparison.html

Produces a multi-metric quality comparison report using paired bootstrap tests. Returns None if metrics are missing, score vectors are empty, score lengths mismatch, or bootstrap parameters are invalid.

```APIDOC
## pub fn quality_comparison

### Description
Produce a multi-metric quality comparison report using paired bootstrap tests.

### Signature
`pub fn quality_comparison(metric_samples: &[QualityMetricSamples<'_>], confidence: f64, n_resamples: usize, seed: u64) -> Option<QualityComparison>`

### Parameters
- **metric_samples** (&[QualityMetricSamples<'_>]) - Required - A slice of quality metric samples to compare.
- **confidence** (f64) - Required - The confidence level for the bootstrap test.
- **n_resamples** (usize) - Required - The number of resamples to perform.
- **seed** (u64) - Required - The seed for the random number generator.

### Returns
- **Option<QualityComparison>** - Returns a `QualityComparison` object if successful, or `None` if input validation fails (e.g., empty metrics, mismatched score lengths, or invalid bootstrap parameters).
```

--------------------------------

### now

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Returns the current physical time.

```APIDOC
## pub fn now(&self) -> Time

### Description
Returns the current physical time according to the configured timer driver, or the wall clock if no timer driver is available.
```

--------------------------------

### from_fsvi

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.InMemoryVectorIndex.html

Loads an InMemoryVectorIndex from an existing FSVI file.

```APIDOC
## pub fn from_fsvi(path: &Path) -> Result<InMemoryVectorIndex, SearchError>

### Description
Reads an entire file-backed index into heap memory, eliminating page-fault latency for subsequent searches.

### Errors
Returns errors from `VectorIndex::open` or vector decoding failures.
```

--------------------------------

### SyncTwoTierSearcher Constructor

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.SyncTwoTierSearcher.html

Creates a new instance of the searcher using an in-memory two-tier index and configuration.

```rust
pub const fn new( index: Arc<InMemoryTwoTierIndex>, config: TwoTierConfig, ) -> SyncTwoTierSearcher
```

--------------------------------

### io

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.Cx.html

Access the I/O capability for async operations.

```APIDOC
## pub fn io(&self) -> Option<&dyn IoCap>

### Description
Returns the I/O capability if configured. This is used for explicit capability-based I/O operations.
```

--------------------------------

### pub fn checkpoint_state(&self) -> CheckpointState

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.Cx.html

Returns a snapshot of the current checkpoint state, including the last checkpoint time, last message, and total count.

```APIDOC
## pub fn checkpoint_state(&self) -> CheckpointState

### Description
Returns a snapshot of the current checkpoint state. This is useful for monitoring task progress and detecting stalled tasks.
```

--------------------------------

### Reborrowing with as_mut

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SearchFuture.html

Shows how to use as_mut to reborrow a Pin<&mut Self> when calling methods that consume the pinned pointer.

```rust
use std::pin::Pin;

impl Type {
    fn method(self: Pin<&mut Self>) {
        // do something
    }

    fn call_method_twice(mut self: Pin<&mut Self>) {
        // `method` consumes `self`, so reborrow the `Pin<&mut Self>` via `as_mut`.
        self.as_mut().method();
        self.as_mut().method();
    }
}
```

--------------------------------

### HashEmbedder::default_256

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.HashEmbedder.html

Creates a default HashEmbedder with 256 dimensions.

```APIDOC
## pub fn default_256() -> HashEmbedder

### Description
Returns a pre-configured HashEmbedder using the FNV-modular algorithm with a fixed dimension of 256, optimized for fast-tier compatibility.
```

--------------------------------

### budget

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Retrieves the current task budget.

```APIDOC
## pub fn budget(&self) -> Budget

### Description
Returns the current budget, which defines resource limits for this task including deadline, poll_quota, cost_quota, and priority.
```

--------------------------------

### Arc::into_raw_with_allocator

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SharedMetricsExporter.html

Consumes the Arc, returning the wrapped pointer and allocator. This is a nightly-only experimental API.

```APIDOC
## Arc::into_raw_with_allocator

### Description
Consumes the `Arc`, returning the wrapped pointer and allocator. To avoid a memory leak the pointer must be converted back to an `Arc` using `Arc::from_raw_in`.

### Signature
`pub fn into_raw_with_allocator(this: Arc<T, A>) -> (*const T, A)`
```

--------------------------------

### HashEmbedder::new

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.HashEmbedder.html

Creates a new HashEmbedder instance with a specified dimension and hashing algorithm.

```APIDOC
## pub fn new(dimension: usize, algorithm: HashAlgorithm) -> HashEmbedder

### Description
Initializes a new hash embedder with the specified vector dimension and hashing algorithm. Note that this will panic if the dimension provided is zero.

### Parameters
- **dimension** (usize) - The desired size of the output embedding vector.
- **algorithm** (HashAlgorithm) - The specific hashing algorithm to use for embedding generation.
```

--------------------------------

### EmbedderStack Methods

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.EmbedderStack.html

Methods for creating, configuring, and inspecting the EmbedderStack.

```APIDOC
## pub fn from_parts(fast: Arc<dyn Embedder>, quality: Option<Arc<dyn Embedder>>) -> EmbedderStack

Builds an EmbedderStack from explicit fast and quality embedder components.

## pub fn auto_detect() -> Result<EmbedderStack, SearchError>

Auto-detects the best available embedders from default search paths. Returns SearchError::EmbedderUnavailable if no fast embedder is found.

## pub fn auto_detect_with(model_root: Option<&Path>) -> Result<EmbedderStack, SearchError>

Auto-detects embedders using an optional explicit model root path override.

## pub fn with_mrl_target_dim(self, target_dim: usize) -> Result<EmbedderStack, SearchError>

Applies MRL-style dimensionality reduction to the stack. Returns SearchError::InvalidConfig if target_dim is zero.

## pub fn diagnose(&self) -> ModelAvailabilityDiagnostic

Generates a diagnostic report regarding model availability, including cache paths and manual download suggestions.

## pub fn degradation_message(&self) -> Option<String>

Returns a user-facing message if the stack is operating in a degraded mode.
```

--------------------------------

### Cx::pressure

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.Cx.html

Reads the current system pressure handle attached to the context.

```APIDOC
## pub fn pressure(&self) -> Option<&SystemPressure>

### Description
Returns the current system pressure handle if one is attached to the context. Returns None if no pressure handle is present.
```

--------------------------------

### Cx::emit_evidence

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Emits an evidence entry to the attached sink.

```APIDOC
## pub fn emit_evidence(&self, entry: &EvidenceLedger)

### Description
Emits an evidence entry to the attached sink, if one is configured. This is a no-op if no sink is present.

### Parameters
- **entry** (&EvidenceLedger) - The evidence entry to record.
```

--------------------------------

### search_top_k_with_params

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.InMemoryVectorIndex.html

Performs a brute-force top-k search with configurable parallelism.

```APIDOC
## pub fn search_top_k_with_params(&self, query: &[f32], limit: usize, filter: Option<&dyn SearchFilter>, params: SearchParams) -> Result<Vec<VectorHit>, SearchError>

### Description
Executes a brute-force top-k search allowing for configurable parallelism via `SearchParams`.

### Errors
Returns `SearchError::DimensionMismatch` when `query.len() != dimension`.
```

--------------------------------

### search

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.TwoTierSearcher.html

Execute progressive search, calling on_phase as results become available.

```APIDOC
## pub async fn search(&self, cx: &Cx, query: &str, k: usize, text_fn: impl Fn(&str) -> Option<String> + Send + Sync, on_phase: impl FnMut(SearchPhase) + Send) -> Result<TwoTierMetrics, SearchError>

### Description
Execute progressive search, calling `on_phase` as results become available. Fires `SearchPhase::Initial` first, then optionally `SearchPhase::Refined` or `SearchPhase::RefinementFailed`.

### Parameters
- **cx** (Capability context) - Required - Capability context for cancellation.
- **query** (str) - Required - The search query string.
- **k** (usize) - Required - Maximum number of results per phase.
- **text_fn** (Fn) - Required - Retrieves document text by doc_id for reranking and exclusion-query filtering.
- **on_phase** (FnMut) - Required - Callback invoked once per search phase.
```

--------------------------------

### Unwrap Result or Default

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/type.SearchResult.html

Returns the Ok value or the default value of the type if the result is an Err.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

--------------------------------

### Chain Results with And

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/type.SearchResult.html

Returns the provided result if the current result is Ok, otherwise returns the Err.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));

let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));

let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

--------------------------------

### search

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/struct.TwoTierSearcher.html

Executes a progressive search, invoking a callback for each search phase. Returns metrics from all phases.

```APIDOC
## pub async fn search(&self, cx: &Cx, query: &str, k: usize, text_fn: impl Fn(&str) -> Option<String> + Send + Sync, on_phase: impl FnMut(SearchPhase) + Send) -> Result<TwoTierMetrics, SearchError>

### Description
Executes a progressive search, calling `on_phase` as results become available. Fires `SearchPhase::Initial` first, then optionally `SearchPhase::Refined` or `SearchPhase::RefinementFailed`.

### Parameters
- **cx** (Capability context) - Required - Capability context for cancellation.
- **query** (str) - Required - The search query string.
- **k** (usize) - Required - Maximum number of results per phase.
- **text_fn** (Fn) - Required - Retrieves document text by doc_id for reranking and exclusion-query filtering.
- **on_phase** (FnMut) - Required - Callback invoked once per search phase.

### Errors
- Returns `SearchError::Cancelled` if the operation is cancelled via `cx`.
- Returns `SearchError::EmbeddingFailed` if fast embedding fails and no lexical backend is available as fallback.
```

--------------------------------

### Demonstrating unsafe Pin usage with Rc

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SearchFuture.html

Illustrates how calling Pin::new_unchecked on an Rc can lead to undefined behavior due to potential aliasing that bypasses pinning restrictions.

```rust
use std::rc::Rc;
use std::pin::Pin;

fn move_pinned_rc<T>(mut x: Rc<T>) {
    // This should mean the pointee can never move again.
    let pin = unsafe { Pin::new_unchecked(Rc::clone(&x)) };
    {
        let p: Pin<&T> = pin.as_ref();
        // ...
    }
    drop(pin);

    let content = Rc::get_mut(&mut x).unwrap(); // Potential UB down the road ⚠️
    // Now, if `x` was the only reference, we have a mutable reference to
    // data that we pinned above, which we could use to move it as we have
    // seen in the previous example. We have violated the pinning API contract.
}
```

--------------------------------

### Handle cancellation with checkpoint

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Use the checkpoint method with the ? operator to handle task cancellation concisely.

```rust
async fn do_work(cx: &Cx) -> Result<(), Error> {
    // Use checkpoint with ? for concise cancellation handling
    cx.checkpoint()?;

    expensive_operation().await?;

    cx.checkpoint()?;

    another_operation().await?;

    Ok(())
}
```

--------------------------------

### trace

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Traces an event for observability, associated with the current task and region.

```APIDOC
## pub fn trace(&self, message: &str)

### Description
Traces an event for observability. Trace events are associated with the current task and region, enabling structured observability.

### Parameters
- **message** (&str) - The trace message to record.
```

--------------------------------

### Create new Arc

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SharedMetricsExporter.html

Allocates a new Arc containing the provided data.

```rust
use std::sync::Arc;

let five = Arc::new(5);
```

--------------------------------

### Pinning closure captures safely

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SearchFuture.html

Demonstrates the risks of using Pin::new_unchecked on moved closure captures and provides a safer alternative using the pin! macro.

```rust
use std::pin::Pin;
use std::task::Context;
use std::future::Future;

fn move_pinned_closure(mut x: impl Future, cx: &mut Context<'_>) {
    // Create a closure that moves `x`, and then internally uses it in a pinned way.
    let mut closure = move || unsafe {
        let _ignore = Pin::new_unchecked(&mut x).poll(cx);
    };
    // Call the closure, so the future can assume it has been pinned.
    closure();
    // Move the closure somewhere else. This also moves `x`!
    let mut moved = closure;
    // Calling it again means we polled the future from two different locations,
    // violating the pinning API contract.
    moved(); // Potential UB ⚠️
}
```

```rust
use std::pin::pin;
use std::task::Context;
use std::future::Future;

fn move_pinned_closure(mut x: impl Future, cx: &mut Context<'_>) {
    let mut x = pin!(x);
    // Create a closure that captures `x: Pin<&mut _>`, which is safe to move.
    let mut closure = move || {
        let _ignore = x.as_mut().poll(cx);
    };
    // Call the closure, so the future can assume it has been pinned.
    closure();
    // Move the closure somewhere else.
    let mut moved = closure;
    // Calling it again here is fine (except that we might be polled a future that already
    // returned `Poll::Ready`, but that is a separate problem).
    moved();
}
```

--------------------------------

### for_testing_with_remote

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Creates a test-only capability context with a remote capability.

```APIDOC
## pub fn for_testing_with_remote(cap: RemoteCap) -> Cx

### Description
Creates a test-only capability context with a RemoteCap for testing remote task spawning without a real network transport.
```

--------------------------------

### Constructing Uninitialized Arc

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/type.SharedMetricsExporter.html

new_uninit allows for deferred initialization of Arc contents.

```rust
use std::sync::Arc;

let mut five = Arc::<u32>::new_uninit();

// Deferred initialization:
Arc::get_mut(&mut five).unwrap().write(5);

let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

--------------------------------

### scope_with_budget

Source: https://docs.rs/frankensearch/0.3.2/frankensearch/prelude/struct.Cx.html

Creates a Scope bound to this context’s region with a custom budget.

```APIDOC
## pub fn scope_with_budget(&self, budget: Budget) -> Scope<'static>

### Description
Creates a Scope bound to this context’s region with a custom budget. This is typically used by the scope! macro when a budget is specified.
```
Tokens:
Raw