Struct MicroscopeReader 

pub struct MicroscopeReader {
    pub headers: Mmap,
    pub data: DataStore,
    pub block_count: usize,
    pub header_stride: usize,
    pub depth_ranges: [(u32, u32); 9],
    pub text_index: Option<TextIndex>,
    pub append_log: Vec<AppendEntry>,
    /* private fields */
}

High-performance memory-mapped reader for the Microscope index.

Fields

headers: Mmap

data: DataStore

block_count: usize

header_stride: usize

depth_ranges: [(u32, u32); 9]

text_index: Option<TextIndex>

append_log: Vec<AppendEntry>

Hot append log, loaded at open. Cached because the combined ranked search reads it on every query and it only changes on append.

append_log_stamp is the (len, mtime) of the file the cache was built from. The ranked search re-validates it against the file before use: one metadata() call (~1 µs) instead of a full re-read (~230 µs), so a reader held across stores still sees new appends. See find_text_all_ranked.

Implementations

impl MicroscopeReader

pub fn open(config: &Config) -> Result<Self, String>

pub fn header(&self, i: usize) -> BlockHeader

pub unsafe fn header_unchecked(&self, i: usize) -> BlockHeader

Read the header for block i without a bounds check.

Safety

i must be strictly less than self.block_count. Violating this reads outside the mmap region, which is undefined behavior.

pub fn text(&self, i: usize) -> &str

pub fn look( &self, config: &Config, x: f32, y: f32, z: f32, zoom: u8, k: usize, ) -> Vec<(f32, usize, bool)>

The MICROSCOPE: exact depth + spatial L2 search.

pub fn look_soft( &self, config: &Config, x: f32, y: f32, z: f32, zoom: u8, k: usize, zw: f32, ) -> Vec<(f32, usize, bool)>

4D soft zoom search with SIMD.

pub fn radial_search( &self, config: &Config, x: f32, y: f32, z: f32, depth: u8, radius: f32, k: usize, ) -> ResultSet

Radial search: find all blocks within radius of (x, y, z) at a specific depth. Returns a ResultSet with the closest match as primary and neighbors distance-weighted.

pub fn find_text(&self, query: &str, k: usize) -> Vec<(u8, usize)>

Text search

The idiom here is to_lowercase() + contains() on purpose. The allocation-free contains_ci alternative was implemented and measured at ~5× slower (see its doc comment and tests/contains_ci.rs); the standard search is SIMD two-way and the per-block temporary is not the bottleneck it looks like. The win for this function comes from the inverted index (see candidate_blocks), not from the predicate.

pub fn find_text_ranked(&self, query: &str, k: usize) -> Vec<(u8, usize, f32)>

Text search ranked by relevance rather than by depth.

The previous behaviour sorted by depth and truncated, so a shallow noise fragment always outranked the exact fact the user asked for. This scores each match on (a) how precisely it matches the query, (b) the block’s recorded importance, and (c) specificity (a short block that is mostly the query is a stronger hit than a long block that merely contains it), then drops near-tied noise via a relative score floor.

pub fn refresh_append_log(&mut self, config: &Config)

Re-read the hot append log from disk.

The log is cached at open because the ranked search reads it on every query. Explicit refresh is available for callers that store and search through the same reader and cannot tolerate the automatic validation heuristic below (see find_text_all_ranked).

pub fn find_text_all_ranked( &mut self, _config: &Config, query: &str, k: usize, ) -> Vec<(u8, usize, bool, f32)>

Ranked text search across the main index and the hot append log.

The append log is cached on the reader rather than re-read per query. The cache validates itself against append.bin’s (len, mtime) on every call — one metadata() syscall instead of a ~230 µs re-read — so a reader held across stores still sees entries appended since it was opened, and the result is always the same as a fresh reader’s.

pub fn find_text_all( &self, config: &Config, query: &str, k: usize, ) -> Vec<(u8, usize, bool)>

Text search across both the immutable main index and the hot append log. Append entries use virtual indices starting at 1_000_000.

pub fn print_result_with_limit( &self, i: usize, dist: f32, preview_limit: Option<usize>, )

Print one result. The full block text is shown: a 256-byte block fits on one line, and truncating at 70 characters could hide the very fact the user searched for. preview_limit can still cap it for narrow terminals.

pub fn print_result(&self, i: usize, dist: f32)

impl MicroscopeReader

pub fn look_with_options( &self, config: &Config, x: f32, y: f32, z: f32, zoom: u8, k: usize, opts: Option<&MemoryQueryOptions>, ) -> Vec<(f32, usize, bool)>

Project-scoped variant of look.

pub fn look_soft_with_options( &self, config: &Config, x: f32, y: f32, z: f32, zoom: u8, k: usize, zw: f32, opts: Option<&MemoryQueryOptions>, ) -> Vec<(f32, usize, bool)>

Project-scoped variant of look_soft.

pub fn radial_search_with_options( &self, config: &Config, x: f32, y: f32, z: f32, depth: u8, radius: f32, k: usize, opts: Option<&MemoryQueryOptions>, ) -> ResultSet

Project-scoped variant of radial_search.

pub fn find_text_with_options( &self, query: &str, k: usize, opts: Option<&MemoryQueryOptions>, ) -> Vec<(u8, usize)>

Project-scoped variant of find_text.

pub fn find_text_all_with_options( &self, config: &Config, query: &str, k: usize, opts: Option<&MemoryQueryOptions>, ) -> Vec<(u8, usize, bool)>

Project-scoped variant of find_text_all.