change_capsule/lib.rs
1//! Isolated, recoverable code-change attempts backed by ordinary Git worktrees,
2//! sealed into portable receipts that can be verified anywhere.
3//!
4//! Capsule does not run an agent. It gives any agent or automation system
5//! a safe place to work and produces a durable, inspectable result to hand back.
6//!
7//! # Model
8//!
9//! A *capsule* is one attempt at a change. It pins an exact base commit, owns an
10//! ordinary Git worktree on its own branch, and records everything needed to
11//! review the attempt later: checkpoints, verification evidence, a complete
12//! binary-capable patch, a changed-path inventory, and content digests. Several
13//! capsules can start from the same commit and modify the same files without
14//! interfering, because each has its own worktree and index.
15//!
16//! Closing a capsule *seals* it. A sealed result is immutable: later mutation of
17//! the workspace is detected as drift and blocks integration and ordinary
18//! cleanup. Integration is always explicit and refuses anything but a clean
19//! target still at the pinned base.
20//!
21//! # Receipts
22//!
23//! [`CapsuleManager::export_artifacts`] writes a sealed result to a
24//! self-describing directory containing `bundle.json`, `result.json`, and
25//! `result.patch`. That directory is a portable receipt: [`verify_bundle`]
26//! re-checks it with no capsule state and no workspace, so the process that
27//! produced a change and the process that reviews it never need to share a
28//! machine. Given a repository, verification additionally proves the sealed
29//! patch applies to the pinned base and reproduces exactly the sealed bytes and
30//! changed paths. [`attest_bundle`] projects a verified receipt into a standard
31//! in-toto Statement for SLSA/Sigstore tooling; its `proof_boundary` states
32//! machine-readably what the receipt does and does not establish.
33//!
34//! # Evidence
35//!
36//! Verification records come in two kinds, and the difference decides what a
37//! verifier may conclude.
38//!
39//! [`EvidenceInput::Run`] has Capsule spawn the program itself, in the capsule
40//! workspace, with no shell. Capsule observes the exit status and digests the
41//! output, and the record is stored with `executed: true`. Nothing in this API
42//! sets that flag any other way, and both receipt verification and durable-state
43//! validation reject a record that asserts it without the captured-output digest
44//! an execution produces.
45//!
46//! [`EvidenceInput::Claim`] records what a caller says happened elsewhere.
47//! Capsule runs nothing and vouches for nothing, and such a record can never
48//! satisfy [`CloseOptions::executed`] or [`VerifyOptions::strict`].
49//!
50//! Execution narrows the trust boundary rather than removing it: the exit code
51//! was still observed by a Capsule process on the producing host. Every
52//! attestation keeps `producing-host-was-uncompromised` in `does_not_prove`.
53//!
54//! # Orchestration protocol
55//!
56//! [`Capabilities::current`] is a static compatibility contract: an independent
57//! capability schema version, protocol versions, stable versioned feature
58//! identifiers, supported schemas, and byte limits. It touches no state and no
59//! Git, so a coordinator can probe an unknown installation safely. It negotiates
60//! protocol features only, never trust in the binary or its host.
61//!
62//! [`CapsuleManager::create_idempotent`] binds a caller-supplied opaque key to
63//! one capsule identity within one canonical state root, publishing a durable
64//! reservation before any capsule, branch, worktree, or manifest side effect, so
65//! a retry after a timeout or crash resumes that same identity instead of
66//! creating a second attempt. [`CapsuleManager::lookup_idempotency_key`] and
67//! [`CapsuleManager::lookup_idempotency_key_at`] resolve one key directly,
68//! without enumerating state. Keys are local orchestration metadata, not
69//! credentials, and never appear in a portable receipt.
70//!
71//! # Example
72//!
73//! ```no_run
74//! use change_capsule::{
75//! CapsuleManager, CloseOptions, CreateOptions, EvidenceInput, VerifyOptions, verify_bundle,
76//! };
77//!
78//! let manager = CapsuleManager::open_default()?;
79//! let capsule = manager.create(CreateOptions::new(".").with_label("candidate a"))?;
80//!
81//! // Launch any external tool with capsule.workspace_path as its directory.
82//! // Then have Capsule run the verification command, so the result is observed
83//! // rather than asserted.
84//! manager.add_evidence(&capsule.id, EvidenceInput::run(["cargo", "test"]))?;
85//!
86//! // Sealing refuses to proceed unless that command passed on this exact patch.
87//! let result = manager.close(&capsule.id, CloseOptions::executed())?;
88//! manager.export_artifacts(&capsule.id, "./receipt")?;
89//!
90//! // Anywhere else, holding only ./receipt and a clone of the repository:
91//! let report = verify_bundle("./receipt", &VerifyOptions::strict("."))?;
92//! assert_eq!(report.patch_sha256, result.patch_sha256);
93//! # Ok::<(), change_capsule::Error>(())
94//! ```
95//!
96//! # Division of responsibility
97//!
98//! This crate owns the attempt lifecycle, provenance, artifacts, and receipts.
99//! The caller owns process launch, model choice, prompts, credentials,
100//! sandboxing, and any remote artifact transport. The workspace is an isolation boundary for Git
101//! state, not a security sandbox; run untrusted code under an external sandbox.
102//!
103//! # Feature flags
104//!
105//! The default `cli` feature builds the `capsule` binary and pulls in Clap.
106//! Library-only embedders can disable default features.
107
108pub mod artifact;
109pub mod attestation;
110pub mod capabilities;
111pub mod error;
112mod exec;
113mod git;
114pub mod idempotency;
115mod manager;
116pub mod model;
117mod path;
118pub mod signature;
119mod state;
120pub mod verify;
121
122pub use artifact::{ArtifactReader, ArtifactSink, PublishedArtifact};
123pub use attestation::{
124 CHANGE_PREDICATE_TYPE, ChangePredicate, IN_TOTO_STATEMENT_TYPE, ProofBoundary,
125 RecordedEvidence, ResourceDescriptor, Statement, attest_bundle, change_statement,
126};
127pub use capabilities::{
128 CAPABILITY_SCHEMA_VERSION, Capabilities, CapabilityLimits, CapabilitySchemas,
129 IDEMPOTENCY_KEY_BYTES_LIMIT, IDEMPOTENCY_RECORD_SCHEMA_VERSION, LABEL_BYTES_LIMIT,
130 LINK_KEY_BYTES_LIMIT, LINK_VALUE_BYTES_LIMIT, LINKS_LIMIT, PROTOCOL_VERSION,
131};
132pub use error::{Error, Result};
133pub use idempotency::{IdempotencyLookup, IdempotencyRecordInspection, IdempotencyStatus};
134pub use manager::{
135 Author, CapsuleManager, CheckpointOptions, CloseOptions, CreateOptions, EvidenceInput,
136 IntegrateOptions,
137};
138pub use model::{
139 ArtifactBundle, ArtifactDescriptor, ArtifactKind, BUNDLE_SCHEMA_VERSION, Capsule,
140 CapsuleHealth, CapsuleListing, CapsuleResult, CapsuleState, CapsuleStatus, CapsuleSummary,
141 Checkpoint, CheckpointJournal, Cleanup, Evidence, ExportReport, GitPath, HARD_PATCH_BYTES,
142 Integration, RecoveryAction, ResultKind, ResultRef, SCHEMA_VERSION, UnreadableRecord,
143 VerificationReport,
144};
145pub use signature::{
146 GeneratedKeypair, bundle_signature_commitment, derive_public_key, generate_keypair,
147 sign_bundle, sign_bundle_bytes, verify_bundle_signature, verify_bundle_signature_bytes,
148};
149pub use state::default_state_root;
150pub use verify::{VerifyOptions, verify_authenticated_bundle, verify_bundle};