claw_branch/
lib.rs

1//! # claw-branch
2//!
3//! A Rust library for isolated, SQLite-backed agent branch management.
4//!
5//! `claw-branch` gives AI agents a structured way to diverge from a shared knowledge
6//! baseline, explore changes in isolation, diff and merge back, and evaluate outcomes
7//! in a fully sandboxed environment — all backed by SQLite and enforced through a
8//! strongly-typed async API.
9//!
10//! ## Core concepts
11//!
12//! | Concept | Description |
13//! |---------|-------------|
14//! | **Branch** | An isolated SQLite database snapshot with its own lifecycle state |
15//! | **Trunk** | The canonical baseline branch; all other branches fork from it |
16//! | **Fork** | Creates a copy-on-write snapshot of a parent branch |
17//! | **Diff** | Entity-level comparison between two branches |
18//! | **Merge** | Three-way merge with configurable conflict resolution strategy |
19//! | **Commit** | Selective cherry-pick of entities from one branch to another |
20//! | **Sandbox** | Temporary evaluation environment for speculative agent work |
21//! | **DAG** | Directed acyclic graph tracking branch lineage |
22//!
23//! ## Quick-start
24//!
25//! ```rust,ignore
26//! use claw_branch::prelude::*;
27//! use std::path::PathBuf;
28//!
29//! #[tokio::main]
30//! async fn main() -> anyhow::Result<()> {
31//!     let config = BranchConfig::builder()
32//!         .workspace_dir(PathBuf::from("/tmp/demo"))
33//!         .build()?;
34//!
35//!     let engine = BranchEngine::new(config, std::path::Path::new("/data/source.db")).await?;
36//!
37//!     // Fork a feature branch from trunk
38//!     let feature = engine.fork_trunk("feature/summariser").await?;
39//!
40//!     // Diff against trunk
41//!     let trunk = engine.trunk().await?;
42//!     let diff  = engine.diff(trunk.id, feature.id).await?;
43//!     println!("changed={}", diff.stats.modified);
44//!
45//!     // Simulate an agent workload and get a recommendation
46//!     let report = engine.simulate(feature.id, SimulationScenario {
47//!         name: "trial".into(),
48//!         description: "test run".into(),
49//!         max_ops: Some(100),
50//!         timeout_secs: Some(30),
51//!         seed_data: None,
52//!     }, |pool| async move {
53//!         // agent writes to pool…
54//!         Ok(serde_json::json!({"status": "done"}))
55//!     }).await?;
56//!
57//!     match report.recommendation {
58//!         Recommendation::Commit => { engine.commit_to_trunk(feature.id).await?; }
59//!         Recommendation::Discard => { engine.discard(feature.id).await?; }
60//!         Recommendation::NeedsReview(notes) => println!("Review: {notes:?}"),
61//!     }
62//!
63//!     Ok(())
64//! }
65//! ```
66
67#![deny(missing_docs)]
68#![deny(clippy::unwrap_used)]
69#![deny(clippy::expect_used)]
70#![deny(clippy::panic)]
71
72/// Branch management primitives.
73pub mod branch;
74/// Selective commit and history helpers.
75pub mod commit;
76/// Shared configuration for branch operations.
77pub mod config;
78/// DAG lineage graph support.
79pub mod dag;
80/// Diff extraction and reporting.
81pub mod diff;
82/// Top-level engine orchestration.
83pub mod engine;
84/// Error types used across the crate.
85pub mod error;
86/// Guard-aware wrapper around the branch engine.
87#[cfg(feature = "guarded")]
88pub mod guarded;
89/// Merge algorithms and conflict handling.
90pub mod merge;
91/// Metrics collection and reporting.
92pub mod metrics;
93/// Simulation sandbox support.
94pub mod sandbox;
95/// Snapshot creation, verification, and garbage collection.
96pub mod snapshot;
97/// Shared domain types.
98pub mod types;
99
100// ── Primary re-exports ────────────────────────────────────────────────────────
101
102pub use config::{BranchConfig, BranchConfigBuilder};
103pub use engine::{BranchConfigError, BranchEngine, BranchEngineBuilder};
104pub use error::{BranchError, BranchResult};
105#[cfg(feature = "guarded")]
106pub use guarded::GuardedBranchEngine;
107
108// types
109pub use types::{
110    Branch, BranchMetrics, BranchStatus, CommitLogEntry, CommitResult, DiffKind, DiffResult,
111    DiffStats, EntityDiff, EntityType, FieldDiff, MergeConflict, MergeResult, SimulationOutcome,
112    WorkspaceReport,
113};
114
115// diff
116pub use diff::formatter::DiffSummary;
117
118// merge
119pub use merge::{resolver::ResolvedValue, strategies::MergeStrategy, three_way::MergePreview};
120
121// commit
122pub use commit::{
123    cherry::{CherryPick, EntitySelection},
124    selective::SelectiveCommit,
125    validator::{CommitValidator, ValidationReport},
126};
127
128// sandbox
129pub use sandbox::{
130    environment::{SandboxStatus, SimulationEnvironment, SimulationScenario},
131    evaluator::{EvaluationReport, Recommendation, SandboxEvaluator},
132    runner::SandboxRunner,
133};
134
135// metrics
136pub use metrics::{
137    divergence::{compute_score, divergence_label, time_weighted_score},
138    reporter::MetricsReporter,
139    tracker::{MetricsTracker, OpKind},
140};
141
142// snapshot GC
143pub use snapshot::gc::GcReport;
144
145// ── Prelude ───────────────────────────────────────────────────────────────────
146
147/// Convenience re-exports for typical library consumers.
148///
149/// ```rust,ignore
150/// use claw_branch::prelude::*;
151/// ```
152pub mod prelude {
153    pub use crate::{
154        Branch, BranchConfig, BranchEngine, BranchError, BranchResult, BranchStatus, CherryPick,
155        EvaluationReport, MergeStrategy, Recommendation, SimulationScenario, WorkspaceReport,
156    };
157}
claw_branch/lib.rs

claw_branch/
lib.rs
