1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
//! Isolated, recoverable code-change attempts backed by ordinary Git worktrees,
//! sealed into portable receipts that can be verified anywhere.
//!
//! Capsule does not run an agent. It gives any agent or automation system
//! a safe place to work and produces a durable, inspectable result to hand back.
//!
//! # Model
//!
//! A *capsule* is one attempt at a change. It pins an exact base commit, owns an
//! ordinary Git worktree on its own branch, and records everything needed to
//! review the attempt later: checkpoints, caller-recorded verification evidence,
//! a complete binary-capable patch, a changed-path inventory, and content
//! digests. Several capsules can start from the same commit and modify the same
//! files without interfering, because each has its own worktree and index.
//!
//! Closing a capsule *seals* it. A sealed result is immutable: later mutation of
//! the workspace is detected as drift and blocks integration and ordinary
//! cleanup. Integration is always explicit and refuses anything but a clean
//! target still at the pinned base.
//!
//! # Receipts
//!
//! [`CapsuleManager::export_artifacts`] writes a sealed result to a
//! self-describing directory containing `bundle.json`, `result.json`, and
//! `result.patch`. That directory is a portable receipt: [`verify_bundle`]
//! re-checks it with no capsule state and no workspace, so the process that
//! produced a change and the process that reviews it never need to share a
//! machine. Given a repository, verification additionally proves the sealed
//! patch applies to the pinned base and reproduces exactly the sealed bytes and
//! changed paths.
//!
//! # Example
//!
//! ```no_run
//! use change_capsule::{CapsuleManager, CloseOptions, CreateOptions};
//!
//! let manager = CapsuleManager::open_default()?;
//!
//! let mut options = CreateOptions::new(".");
//! options.label = Some("candidate implementation".into());
//! let capsule = manager.create(options)?;
//!
//! // Launch any external tool with capsule.workspace_path as its directory,
//! // then record whatever verification the caller performed.
//!
//! let result = manager.close(&capsule.id, CloseOptions::default())?;
//! println!("sealed {} changed paths", result.changed_paths.len());
//! # Ok::<(), change_capsule::Error>(())
//! ```
//!
//! # Division of responsibility
//!
//! This crate owns the attempt lifecycle, provenance, artifacts, policy, audit
//! records, and state administration. The caller owns process launch, model
//! choice, prompts, credentials, sandboxing, verification execution, and any
//! remote artifact transport. The workspace is an isolation boundary for Git
//! state, not a security sandbox; run untrusted code under an external sandbox.
//!
//! # Feature flags
//!
//! The default `cli` feature builds the `capsule` binary and pulls in Clap.
//! Library-only embedders can disable default features.
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use default_state_root;
pub use ;