Cairn

The Problem

You spend 3 hours coding. You run cargo build. 500 errors. You don't remember what you changed.

Git shows you a diff with 800 lines across 12 files. You spend 2 hours trying to undo your changes. You give up and git reset --hard to your last commit from yesterday, losing everything.

Cairn solves this: Every successful build is automatically captured as a patch. One command rolls back to any previous working state.

Build-Gated Snapshots

With Git, you can commit anything—broken code, untested changes, WIP disasters. Your history becomes polluted with commits that don't even compile.

Cairn's guarantee: Every snapshot in history is guaranteed to build successfully.

$ cargo build
    Finished dev [unoptimized + debuginfo] target(s) in 2.34s
✓ Cairn: Snapshot created (a3f8d9e1)

$ cairn list
● a3f8d9e1 - just now - "Successful build"  ← GUARANTEED TO WORK
● d7e2c1f - 1 hr ago - "Successful build"   ← GUARANTEED TO WORK
● 9f1d3e7 - yesterday - "Successful build"  ← GUARANTEED TO WORK

Build succeeds → Cairn saves it automatically. Build fails → Nothing happens. You cannot pollute history with broken code.

How It Works

Automatic Snapshots

• cargo build succeeds → Cairn creates a patch automatically
• cargo build fails → Nothing happens
• Every patch in history is a working build
• No manual snapshot command—the compiler is the gatekeeper

Instant Rollback

$ cairn rollback a3f8d9e1
Restored to patch a3f8d9e1 (37 minutes ago)
✓ Rolled back 10,000 files (1 changed) in 16ms

$ cargo build
    Finished dev [unoptimized + debuginfo] target(s) in 0.23s

Patch-Based, Not Snapshot-Based

• Stores what changed, not entire file copies
• 420 bytes for a typical patch vs 700+ bytes for JSON
• Cryptographically verified (BLAKE3)
• Stored in VSF format (efficient, self-describing)
• Reed-Solomon error correction (2x bloat, 10,000x reliability)

Technical Details

VSF Encoding

Patches stored in Versatile Storage Format:

• Metadata: author, parent, message, build status
• Operations: line-based diffs with file paths
• Build output: cargo hash for verification
• BLAKE3 provenance hash (integrity)
• Huffman compression on strings (36% smaller)

Race Condition Solved

If you edit files while build is running, Cairn snapshots what cargo actually compiled, not what's on disk when the build finishes. Uses cargo's fingerprint as source of truth.

Atomic Operations

• Build complete patch in temp directory
• Use hardlinks for unchanged files (zero copy)
• Atomic directory swap (rename is atomic on all filesystems)
• Update state file (single atomic write with Reed-Solomon)
• If crash happens: repository stays consistent

Prior Art

Cairn builds on:

• Pijul - Patch theory with commutation properties
• Darcs - Original theory of patches (2002)
• Git - Content-addressed storage (without the broken merges)
• BTRFS - Copy-on-write snapshots (but filesystem-independent)

What's novel:

• Build-gated snapshots (not time-based or manual)
• Cargo fingerprint as source-of-truth (solves race conditions)
• VSF encoding (smaller, faster, cryptographically verified)
• Hardlink optimization (instant rollback for large projects)

Status

Cairn is in active development. Linear history only (no merges yet—coming with commutation). Rust-specific for now, can be adapted for other languages later.