Struct BranchEngine 

pub struct BranchEngine { /* private fields */ }

Unified coordinator for all claw-branch capabilities.

BranchEngine is the primary entry point for library consumers. It owns all subsystems and exposes a single, consistent async API.

This engine does not perform authorization checks. Use it when your runtime already validates caller permissions externally.

For workspace-scoped authorization checks at this crate boundary, enable the guarded feature and use GuardedBranchEngine.

Quick-start

use claw_branch::{BranchConfig, BranchEngine};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = BranchConfig::builder()
        .workspace_dir(PathBuf::from("/tmp/myproject"))
        .build()?;
    let engine = BranchEngine::new(config, Path::new("/data/trunk.db")).await?;

    let feature = engine.fork_trunk("feature/my-idea").await?;
    let diff    = engine.diff(engine.trunk().await?.id, feature.id).await?;
    println!("{} entities changed", diff.stats.modified);
    Ok(())
}

Implementations

impl BranchEngine

pub async fn new( config: BranchConfig, trunk_db_path: &Path, ) -> BranchResult<Self>

Creates a new workspace, initialising all subsystems and creating the trunk branch.

trunk_db_path is the source database that will be copied into the trunk branch snapshot.

pub async fn open(config: BranchConfig) -> BranchResult<Self>

Opens an existing workspace without creating a new trunk.

pub fn config(&self) -> &BranchConfig

Returns the engine configuration.

pub fn store(&self) -> Arc<BranchStore>

Returns the shared branch store.

pub fn dag(&self) -> Arc<DagGraph>

Returns the shared DAG graph.

pub fn lifecycle(&self) -> Arc<BranchLifecycle>

Returns the lifecycle coordinator.

pub async fn get(&self, id: Uuid) -> BranchResult<Branch>

Retrieves a branch by ID.

pub async fn get_by_name(&self, name: &str) -> BranchResult<Branch>

Retrieves a branch by human-readable name within the workspace.

pub async fn list( &self, status: Option<BranchStatus>, ) -> BranchResult<Vec<Branch>>

Lists all branches in the workspace, optionally filtered by status.

pub async fn trunk(&self) -> BranchResult<Branch>

Returns the trunk branch.

pub async fn fork( &self, parent_id: Uuid, name: &str, description: Option<&str>, ) -> BranchResult<Branch>

Forks a new branch from parent_id.

pub async fn fork_trunk(&self, name: &str) -> BranchResult<Branch>

Forks a new branch from the trunk.

pub async fn discard(&self, id: Uuid) -> BranchResult<()>

Discards a branch, marking it as inactive.

pub async fn archive(&self, id: Uuid) -> BranchResult<()>

Archives a branch.

pub async fn diff(&self, a: Uuid, b: Uuid) -> BranchResult<DiffResult>

Computes the diff between two branches.

pub async fn compare_branches( &self, a: Uuid, b: Uuid, ) -> BranchResult<DiffResult>

Compares two branches using the same semantics as Self::diff.

pub async fn merge( &self, source: Uuid, target: Uuid, strategy: MergeStrategy, ) -> BranchResult<MergeResult>

Merges source into target using the given strategy.

Uses the parent of source as the merge base. Falls back to target as base when no explicit common ancestor is available.

pub async fn merge_preview( &self, source: Uuid, target: Uuid, ) -> BranchResult<MergePreview>

Previews a three-way merge without applying any changes.

pub async fn commit(&self, cherry: CherryPick) -> BranchResult<CommitResult>

Executes a selective cherry-pick commit.

pub async fn cherry_pick( &self, source_id: Uuid, target_id: Uuid, selections: Vec<EntitySelection>, message: Option<String>, ) -> BranchResult<CommitResult>

Cherry-picks selected entities from source into target.

pub async fn commit_to_trunk( &self, source_id: Uuid, ) -> BranchResult<CommitResult>

Commits all entities from source_id to the trunk branch.

pub async fn simulate<F, Fut>( &self, parent_id: Uuid, scenario: SimulationScenario, agent_fn: F, ) -> BranchResult<EvaluationReport>

where F: FnOnce(SqlitePool) -> Fut, Fut: Future<Output = BranchResult<Value>>,

Runs an agent simulation in an isolated sandbox branch.

Returns an evaluation report with diff, metrics, and a promotion recommendation.

pub async fn lineage(&self, branch_id: Uuid) -> BranchResult<Vec<Uuid>>

Returns the ancestor lineage of a branch as an ordered list (root-first).

pub async fn dag_dot(&self) -> BranchResult<String>

Exports the branch DAG as a Graphviz DOT string.

pub async fn metrics(&self, branch_id: Uuid) -> BranchResult<BranchMetrics>

Returns up-to-date metrics for the given branch.

pub async fn workspace_report(&self) -> BranchResult<WorkspaceReport>

Generates a workspace-wide metrics report.

pub async fn gc(&self) -> BranchResult<GcReport>

Runs snapshot garbage collection, deleting orphaned and discarded branch data.

pub async fn start_gc_scheduler(&self) -> BranchResult<()>

Starts the background GC scheduler if it is not already running.

pub async fn stop_gc_scheduler(&self) -> BranchResult<()>

Stops the background GC scheduler and waits for shutdown completion.

pub async fn shutdown(&self) -> BranchResult<()>

Gracefully shuts down background tasks owned by the engine.

Trait Implementations

impl Clone for BranchEngine

fn clone(&self) -> BranchEngine

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.