Code Architecture

TriSeek/
  Cargo.toml                      # workspace root
  crates/
    search-core/src/
      lib.rs                      # re-exports all modules
      query.rs                    # QueryRequest, SearchKind, CaseMode
      result.rs                   # SearchResponse, SearchHit, SearchLineMatch
      planner.rs                  # plan_query(), route_query(), extract_regex_literals()
      trigram.rs                  # encode_trigram(), trigrams_from_bytes()
      repo.rs                     # RepoStats, RepoCategory, IndexMetadata
      metrics.rs                  # ProcessMetrics, SearchMetrics, SessionMetrics
    search-index/src/
      lib.rs                      # re-exports
      engine.rs                   # SearchEngine, IndexBackend, parallel verification
      fastindex.rs                # FastIndex mmap format, write_fast_index()
      build.rs                    # build_index(), update_index(), BuildAccumulator
      walker.rs                   # walk_repository_parallel(), binary detection
      model.rs                    # PersistedIndex, RuntimeIndex, DeltaSnapshot
      storage.rs                  # file I/O: base.bin, delta.bin, fast.idx
    crates/search-cli/src/
      main.rs                     # CLI entry: build, search, session, update, stats
    search-bench/src/
      main.rs                     # benchmark harness with cold/warm trials
  ~/.triseek/indexes/<root-key>/   # generated index directory
    base.bin                      # bincode-serialized full index
    fast.idx                      # mmap binary format (primary)
    delta.bin                     # optional incremental changes
    metadata.json                 # index metadata + repo stats

pub fn plan_query(request: &QueryRequest) -> QueryPlan {
    match request.kind {
        Path         => strategy: PathIndex,
        Literal|Auto => {
            if pattern.len() < 3 => ShortLiteral + DirectScan
            else                  => Literal + Indexed
        }
        Regex        => {
            seeds = extract_regex_literals(pattern)
            if longest_seed >= 3 => RegexAnchored + Indexed
            else                   => RegexWeak + DirectScan
        }
    }
}

pub type Trigram = u32;

pub fn encode_trigram(bytes: &[u8]) -> Option<Trigram> {
    (bytes[0] as u32) << 16
  | (bytes[1] as u32) << 8
  |  bytes[2] as u32
}

pub fn trigrams_from_bytes(bytes: &[u8]) -> Vec<Trigram> {
    let normalized = normalize_for_index(bytes); // lowercase
    normalized.windows(3)
        .filter_map(encode_trigram)
        .collect::<BTreeSet<_>>() // dedup + sort
        .into_iter().collect()
}

pub fn open(index_dir: &Path) -> Result<Self> {
    let metadata = read_index_metadata(index_dir)?;
    let has_delta = delta_exists(index_dir);

    if fast_index_exists(index_dir) && !has_delta {
        // Preferred: zero-copy mmap
        let fast = FastIndex::open(fast_index_path(index_dir))?;
        return Ok(SearchEngine { backend: Fast(fast), .. });
    }

    // Fallback: deserialize + merge
    let base = load_base(index_dir)?;
    let delta = load_delta(index_dir)?;
    let runtime = RuntimeIndex::from_snapshots(base, delta);
    Ok(SearchEngine { backend: Legacy(runtime), .. })
}

fn push(&mut self, file: ScannedFile) {
    let doc_id = self.next_doc_id;  // sequential u32
    self.next_doc_id += 1;

    // Content trigrams → posting lists
    for tri in trigrams_from_bytes(&file.contents) {
        self.content_postings
            .entry(tri).or_default().push(doc_id);
    }

    // Path trigrams → separate posting lists
    for tri in trigrams_from_bytes(file.relative_path.as_bytes()) {
        self.path_postings
            .entry(tri).or_default().push(doc_id);
    }

    // Filename + extension maps for exact lookups
    self.filename_map.entry(file.file_name.to_lowercase())...;
    self.extension_map.entry(ext.to_lowercase())...;
}

match plan.shape {
    Literal | Auto if pattern.len() < 3 => {
        // Too short for trigrams — return all filtered docs
        return filtered_docs;
    }
    Literal | Auto => {
        // Extract trigrams from the literal, intersect posting lists
        let candidates = fast_candidates_for_seed(fast, pattern);
        sorted_intersect(&candidates, &filtered_docs)
    }
    RegexAnchored => {
        // Use extracted literal seeds from the regex
        if regex_has_unescaped_alternation(pattern) {
            // OR pattern: union of each seed's candidates
            seeds.iter().fold(Vec::new(), |acc, seed|
                sorted_union(&acc, &fast_candidates_for_seed(fast, seed))
            )
        } else {
            // AND pattern: intersection of each seed's candidates
            seeds.iter().fold(None, |acc, seed|
                intersect_sorted(acc, fast_candidates_for_seed(fast, seed))
            )
        }
    }
}

pub fn content_postings(&self, trigram: u32) -> Option<Vec<u32>> {
    // O(1) HashMap lookup
    let (offset, count) = self.content_table.get(&trigram)?;

    // Calculate byte position in mmap'd region
    let byte_offset = self.content_postings_offset
                    + (*offset as usize) * 4;

    // Zero-copy: cast raw bytes to &[u32]
    let ptr = self.mmap[byte_offset..].as_ptr() as *const u32;
    let slice = unsafe {
        slice::from_raw_parts(ptr, *count as usize)
    };
    Some(slice.to_vec())
}
// Total cost: 1 HashMap lookup + 1 pointer cast + 1 Vec copy