Struct BranchGarbageCollector 

pub struct BranchGarbageCollector<I: IndexBackend> {
    index: Arc<I>,
    repo_path: Option<PathBuf>,
}

Garbage collector for branch-scoped memories.

Identifies memories associated with git branches that no longer exist and marks them as tombstoned. This helps keep the memory index clean by removing memories that are no longer relevant.

Thread Safety

The garbage collector holds an Arc reference to the index backend, making it safe to share across threads.

Example

use subcog::gc::BranchGarbageCollector;
use subcog::storage::index::SqliteBackend;
use std::sync::Arc;

let backend = Arc::new(SqliteBackend::new("memories.db")?);
let gc = BranchGarbageCollector::new(backend);

// Check for stale branches without making changes
let result = gc.gc_stale_branches("github.com/org/repo", true)?;
if result.has_stale_branches() {
    println!("Stale branches: {:?}", result.stale_branches);
}

Fields

index: Arc<I>

Reference to the index backend for querying and updating memories.

repo_path: Option<PathBuf>

Optional path to the git repository. If None, uses the current working directory.

Implementations

impl<I: IndexBackend> BranchGarbageCollector<I>

pub fn new(index: Arc<I>) -> Self

Creates a new branch garbage collector.

Arguments

• index - Shared reference to the index backend.

Examples

use subcog::gc::BranchGarbageCollector;
use subcog::storage::index::SqliteBackend;
use std::sync::Arc;

let backend = Arc::new(SqliteBackend::in_memory()?);
let gc = BranchGarbageCollector::new(backend);

pub fn with_repo_path(index: Arc<I>, repo_path: &Path) -> Self

Creates a new branch garbage collector with a specific repository path.

Arguments

• index - Shared reference to the index backend.
• repo_path - Path to the git repository.

Examples

use subcog::gc::BranchGarbageCollector;
use subcog::storage::index::SqliteBackend;
use std::sync::Arc;
use std::path::Path;

let backend = Arc::new(SqliteBackend::in_memory()?);
let gc = BranchGarbageCollector::with_repo_path(
    backend,
    Path::new("/path/to/repo"),
);

pub fn gc_stale_branches( &self, project_id: &str, dry_run: bool, ) -> Result<GcResult>

Performs garbage collection on stale branches.

This method:

1. Discovers the git repository from the configured path or CWD
2. Gets all current branches from the repository
3. Queries the index for all distinct branches associated with the project
4. Identifies branches in the index that no longer exist in the repo
5. Tombstones memories associated with stale branches (unless dry_run)

Arguments

• project_id - The project identifier (e.g., “github.com/org/repo”)
• dry_run - If true, only report what would be done without making changes

Returns

A GcResult containing statistics about the operation.

Errors

Returns an error if:

• The git repository cannot be discovered
• The index backend operations fail

Examples

use subcog::gc::BranchGarbageCollector;

// Dry run first
let result = gc.gc_stale_branches("github.com/org/repo", true)?;
println!("{}", result.summary());

// Then actually perform cleanup
if result.has_stale_branches() {
    let result = gc.gc_stale_branches("github.com/org/repo", false)?;
    println!("Cleaned up: {}", result.summary());
}

fn discover_repository(&self) -> Result<Repository>

Discovers the git repository.

fn get_current_branches(repo: &Repository) -> Result<HashSet<String>>

Gets all current branch names from the repository.

fn get_indexed_branches(&self, project_id: &str) -> Result<Vec<String>>

Gets all distinct branch names from the index for a project.

Uses batch query to avoid N+1 pattern (PERF-HIGH-003).

fn count_memories_for_branches( &self, project_id: &str, branches: &[String], ) -> Result<usize>

Counts memories that would be tombstoned for the given branches.

fn tombstone_memories_for_branches( &self, project_id: &str, branches: &[String], ) -> usize

Tombstones memories associated with the given branches.

This is a placeholder that will be enhanced when Task 4.3 adds update_status to the IndexBackend trait.

fn tombstone_branch_memories( &self, project_id: &str, branch: &str, now: u64, ) -> usize

Tombstones all memories for a single branch.

Uses batch query to avoid N+1 pattern (PERF-HIGH-003).

fn try_tombstone_memory(&self, id: &MemoryId, memory: Memory, now: u64) -> bool

Attempts to tombstone a single memory, returning true on success.