claw-branch

The fork/simulate/merge engine for ClawDB.

claw-branch is a Rust library for isolated, SQLite-backed branch workflows. It allows agents and applications to fork from a canonical trunk, experiment safely in isolated branch databases, and merge or commit changes back with explicit diff and conflict semantics.

Architecture overview

┌─────────────────────────────────────────────────────────────────┐
│                         BranchEngine                           │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐    │
│   │ Lifecycle│  │  Commit  │  │  Merge   │  │   Sandbox   │    │
│   │ fork/    │  │ cherry-  │  │ 3-way +  │  │ run/eval    │    │
│   │ archive  │  │ pick/all │  │ resolver │  │ recommendation│   │
│   └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬──────┘    │
│        │              │              │                │           │
│   ┌────▼──────────────▼──────────────▼────────────────▼──────┐   │
│   │                  BranchStore (registry DB)                │   │
│   └───────────────────────────────────────────────────────────┘   │
│                                                                   │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐      │
│   │   DAG    │  │   Diff   │  │ Metrics  │  │  Snapshot   │      │
│   │ lineage  │  │ entity + │  │ tracker/ │  │ copy/verify │      │
│   │ + LCA    │  │ field    │  │ reporter │  │ + gc        │      │
│   └──────────┘  └──────────┘  └──────────┘  └─────────────┘      │
└─────────────────────────────────────────────────────────────────┘

Each branch is a separate SQLite file.
The trunk is the canonical root branch and is never discarded.

Quick-start

use claw_branch::prelude::*;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = BranchConfig::builder()
        .workspace_id(uuid::Uuid::new_v4())
        .branches_dir(PathBuf::from("/tmp/demo/branches"))
        .build()?;

    let engine = BranchEngine::new(config, std::path::Path::new("/data/source.db")).await?;

    // Recommended when using the `guarded` feature:
    // let guarded = GuardedBranchEngine::new(engine, guard);
    // let feature = guarded.fork_trunk(&session, "feature/summariser").await?;

    let feature = engine.fork_trunk("feature/summariser").await?;

    let trunk = engine.trunk().await?;
    let diff = engine.diff(trunk.id, feature.id).await?;
    println!(
        "changed: +{} ~{} -{}",
        diff.stats.added, diff.stats.modified, diff.stats.removed
    );

    let report = engine
        .simulate(
            feature.id,
            SimulationScenario {
                name: "trial-run".into(),
                description: "evaluate summarisation strategy".into(),
                max_ops: Some(100),
                timeout_secs: Some(30),
                seed_data: None,
            },
            |pool| async move {
                let _ = pool;
                Ok(serde_json::json!({"status": "done", "summaries_generated": 42}))
            },
        )
        .await?;

    match report.recommendation {
        Recommendation::Commit => {
            engine.commit_to_trunk(feature.id).await?;
        }
        Recommendation::Discard => {
            engine.discard(feature.id).await?;
        }
        Recommendation::NeedsReview(notes) => {
            println!("manual review required: {notes:?}");
        }
    }

    Ok(())
}

Core concepts

BranchConfig reference

Merge strategies

Simulation flow

1. Fork a temporary simulation branch from a parent.
2. Run agent logic against the simulation SQLite pool.
3. Compute diff and metrics.
4. Produce Recommendation::Commit, Recommendation::Discard, or Recommendation::NeedsReview.
5. Apply workflow policy (promote/discard/review).

Performance Targets (Design Goals)

The figures below are design goals and are verified in benches/branch_bench.rs.

Measured on Apple M2, 2025-Q2, 10k entity seed corpus

• Fork 1k entities: pending baseline refresh in CI bench job
• Diff 10k entities (10% modified): pending baseline refresh in CI bench job
• Merge 100 non-conflicting entities: pending baseline refresh in CI bench job
• Snapshot verify (10MB): pending baseline refresh in CI bench job

Safety guarantees

• No unwrap/expect in library source, enforced with clippy::unwrap_used deny.
• No missing public docs, enforced with missing_docs deny.
• SQLite isolation by branch file, avoiding shared mutable table state.
• DAG cycle prevention before branch edge insertion.
• Atomic merge transactions.
• Snapshot integrity checks using BLAKE3.

Development commands

cargo check --tests
cargo check --benches
cargo test
cargo bench
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings