Skip to main content

Crate change_capsule

Crate change_capsule 

Source
Expand description

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, 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. attest_bundle projects a verified receipt into a standard in-toto Statement for SLSA/Sigstore tooling; its proof_boundary states machine-readably what the receipt does and does not establish.

§Evidence

Verification records come in two kinds, and the difference decides what a verifier may conclude.

EvidenceInput::Run has Capsule spawn the program itself, in the capsule workspace, with no shell. Capsule observes the exit status and digests the output, and the record is stored with executed: true. Nothing in this API sets that flag any other way, and both receipt verification and durable-state validation reject a record that asserts it without the captured-output digest an execution produces.

EvidenceInput::Claim records what a caller says happened elsewhere. Capsule runs nothing and vouches for nothing, and such a record can never satisfy CloseOptions::executed or VerifyOptions::strict.

Execution narrows the trust boundary rather than removing it: the exit code was still observed by a Capsule process on the producing host. Every attestation keeps producing-host-was-uncompromised in does_not_prove.

§Orchestration protocol

Capabilities::current is a static compatibility contract: an independent capability schema version, protocol versions, stable versioned feature identifiers, supported schemas, and byte limits. It touches no state and no Git, so a coordinator can probe an unknown installation safely. It negotiates protocol features only, never trust in the binary or its host.

CapsuleManager::create_idempotent binds a caller-supplied opaque key to one capsule identity within one canonical state root, publishing a durable reservation before any capsule, branch, worktree, or manifest side effect, so a retry after a timeout or crash resumes that same identity instead of creating a second attempt. CapsuleManager::lookup_idempotency_key and CapsuleManager::lookup_idempotency_key_at resolve one key directly, without enumerating state. Keys are local orchestration metadata, not credentials, and never appear in a portable receipt.

§Example

use change_capsule::{
    CapsuleManager, CloseOptions, CreateOptions, EvidenceInput, VerifyOptions, verify_bundle,
};

let manager = CapsuleManager::open_default()?;
let capsule = manager.create(CreateOptions::new(".").with_label("candidate a"))?;

// Launch any external tool with capsule.workspace_path as its directory.
// Then have Capsule run the verification command, so the result is observed
// rather than asserted.
manager.add_evidence(&capsule.id, EvidenceInput::run(["cargo", "test"]))?;

// Sealing refuses to proceed unless that command passed on this exact patch.
let result = manager.close(&capsule.id, CloseOptions::executed())?;
manager.export_artifacts(&capsule.id, "./receipt")?;

// Anywhere else, holding only ./receipt and a clone of the repository:
let report = verify_bundle("./receipt", &VerifyOptions::strict("."))?;
assert_eq!(report.patch_sha256, result.patch_sha256);

§Division of responsibility

This crate owns the attempt lifecycle, provenance, artifacts, and receipts. The caller owns process launch, model choice, prompts, credentials, sandboxing, 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.

Re-exports§

pub use artifact::ArtifactReader;
pub use artifact::ArtifactSink;
pub use artifact::PublishedArtifact;
pub use attestation::CHANGE_PREDICATE_TYPE;
pub use attestation::ChangePredicate;
pub use attestation::IN_TOTO_STATEMENT_TYPE;
pub use attestation::ProofBoundary;
pub use attestation::RecordedEvidence;
pub use attestation::ResourceDescriptor;
pub use attestation::Statement;
pub use attestation::attest_bundle;
pub use attestation::change_statement;
pub use capabilities::CAPABILITY_SCHEMA_VERSION;
pub use capabilities::Capabilities;
pub use capabilities::CapabilityLimits;
pub use capabilities::CapabilitySchemas;
pub use capabilities::IDEMPOTENCY_KEY_BYTES_LIMIT;
pub use capabilities::IDEMPOTENCY_RECORD_SCHEMA_VERSION;
pub use capabilities::LABEL_BYTES_LIMIT;
pub use capabilities::PROTOCOL_VERSION;
pub use error::Error;
pub use error::Result;
pub use idempotency::IdempotencyLookup;
pub use idempotency::IdempotencyRecordInspection;
pub use idempotency::IdempotencyStatus;
pub use model::ArtifactBundle;
pub use model::ArtifactDescriptor;
pub use model::ArtifactKind;
pub use model::BUNDLE_SCHEMA_VERSION;
pub use model::Capsule;
pub use model::CapsuleHealth;
pub use model::CapsuleListing;
pub use model::CapsuleResult;
pub use model::CapsuleState;
pub use model::CapsuleStatus;
pub use model::CapsuleSummary;
pub use model::Checkpoint;
pub use model::CheckpointJournal;
pub use model::Cleanup;
pub use model::Evidence;
pub use model::ExportReport;
pub use model::GitPath;
pub use model::HARD_PATCH_BYTES;
pub use model::Integration;
pub use model::RecoveryAction;
pub use model::ResultKind;
pub use model::ResultRef;
pub use model::SCHEMA_VERSION;
pub use model::UnreadableRecord;
pub use model::VerificationReport;
pub use signature::GeneratedKeypair;
pub use signature::bundle_signature_commitment;
pub use signature::derive_public_key;
pub use signature::generate_keypair;
pub use signature::sign_bundle;
pub use signature::sign_bundle_bytes;
pub use signature::verify_bundle_signature;
pub use signature::verify_bundle_signature_bytes;
pub use verify::VerifyOptions;
pub use verify::verify_authenticated_bundle;
pub use verify::verify_bundle;

Modules§

artifact
Streaming and publication of sealed artifacts.
attestation
in-toto attestation view of a sealed Capsule result.
capabilities
Static machine-readable protocol capability negotiation.
error
Error type shared by every operation in this crate.
idempotency
State-root-scoped idempotent capsule creation records and direct lookup.
model
Durable data types for capsules, sealed results, and artifacts.
signature
Optional detached Ed25519 authenticity for exported receipts.
verify
Offline verification of exported result bundles.

Structs§

Author
Commit identity used for checkpoints and integration commits.
CapsuleManager
Entry point for every capsule operation.
CheckpointOptions
Inputs for committing the workspace’s current state as a checkpoint.
CloseOptions
Requirements a capsule must satisfy before its result is sealed.
CreateOptions
Inputs for creating a capsule.
IntegrateOptions
Inputs for applying a sealed result to a target worktree.

Enums§

EvidenceInput
How a verification record is produced.

Functions§

default_state_root
Resolve the default state directory.