atomic-pijul

KO | EN

gitlite — search

#javascript #typescript #llm #android #rust #linux #docker #macos #nodejs #java #awesome-list #vue #pytorch #ios

(★ 38)

A mathematically sound version control system based on patch theory

atomic-pijul 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Atomic

A mathematically sound distributed version control system that revolutionizes software development through four breakthrough innovations: hybrid patch/snapshot architecture, cryptographic AI attestation, and a unified node-based DAG.

## 🚀 Revolutionary Architecture: Three Core Innovations

### 1. Hybrid Patch/Snapshot Model with Tag Consolidation
**The Problem**: Traditional VCS systems force a choice between patches (semantic precision, exponential complexity) or snapshots (scalable but lossy).

**Atomic's Innovation**: A hybrid model that provides **patch-level semantic precision within development cycles** and **snapshot-like scalability across cycles** through mathematical tag consolidation.

```
Timeline Visualization:

Patch Development Phase:
├─ Change A [root]                    (1 dependency: root)
├─ Change B [A]                       (1 dependency: A)
├─ Change C [A,B]                     (2 dependencies)
├─ Change D [A,B,C]                   (3 dependencies)
└─ Change E [A,B,C,D]                 (4 dependencies: 10 total)

🏷️ TAG v1.0 = Mathematical Snapshot[A,B,C,D,E]

Next Development Phase:
├─ Change F [TAG v1.0] ✨              (1 dependency: equivalent to 5!)
├─ Change G [F]                       (1 dependency)
├─ Change H [F,G]                     (2 dependencies)
└─ Change I [F,G,H]                   (3 dependencies: 7 total vs 21!)
```

**Dependency Reduction Mathematics**:
- **Before Tags**: With 100 changes = 5,050 total dependencies (O(n²))
- **With Tags**: With 100 changes + consolidation = ~200 dependencies (O(n))
- **Reduction**: 96% reduction in dependency complexity

**Result**: Semantic precision where it matters + infinite scalability + O(1) dependency access.

### 2. AI Attestation with Merkle Cryptographic Signatures
**The Problem**: AI contributions lack cryptographic verification and attribution integrity across distributed operations.

**Atomic's Innovation**: **Merkle-tree-based cryptographic attestation** where AI contributions are mathematically verifiable and tamper-evident.

```rust
// Cryptographically signed AI attestation
struct AIAttestation {
    change_hash: Hash,           // Merkle hash of the change
    ai_provider: String,         // "openai", "anthropic", etc.
    model: String,              // "gpt-4", "claude-3", etc.
    attestation_hash: Hash,     // Cryptographic proof
    signature: Signature,       // Merkle signature chain
    confidence: f64,            // Algorithmic confidence
    timestamp: u64,             // Cryptographic timestamp
}

// Verification
fn verify_ai_attestation(attestation: &AIAttestation) -> bool {
    merkle_verify_chain(&attestation.signature, &attestation.change_hash)
}
```

**Features**:
- ✅ **Cryptographic Integrity**: Merkle signatures prevent tampering
- ✅ **Distributed Verification**: Anyone can verify AI attestations
- ✅ **Attribution Preservation**: Atomic doesn't use merges, conflicts, and rebase operations (Patches)
- ✅ **Audit Compliance**: Mathematically provable AI contribution history

### 3. Node-Based DAG with Mathematical Correctness
**The Problem**: Traditional VCS treats different entities (commits, tags, branches) as separate systems, causing complexity and inconsistency.

**Atomic's Innovation**: **Unified node-based dependency DAG** where both changes and tags are first-class nodes with mathematical guarantees.

```rust
// Unified node system
pub enum NodeType {
    Change = 0,  // Semantic patch with hunks
    Tag = 1,     // Consolidating snapshot
}

pub struct Node {
    pub hash: Hash,              // Universal cryptographic ID
    pub node_type: NodeType,     // Type-safe operations
    pub state: Merkle,          // Mathematical state proof
}

// Mathematical properties guaranteed:
// - Commutativity: A + B = B + A
// - Associativity: (A + B) + C = A + (B + C)
// - Consistency: Same change produces same result
// - Completeness: All dependencies are resolvable
```

**Operations**:
```bash
# All operations work on any node type
atomic apply <change-hash>     # Apply change node
atomic apply <tag-hash>        # Apply tag node (consolidated changes)
atomic dependencies <any-hash> # Works for changes OR tags
atomic log <any-hash>          # Unified history view
```

**Mathematical Guarantees**:
- 🧮 **Commutative Operations**: Changes can be applied in any order
- 🧮 **Associative Grouping**: Dependency grouping doesn't affect results
- 🧮 **Consistency Proofs**: Same logical change works across all compatible states
- 🧮 **Conflict-Free Resolution**: Automatic semantic conflict resolution

## 🎯 Business Value Propositions

### AI-Scale Development
- **100+ AI Agents**: Coordinate simultaneously without conflicts
- **Mathematical Correctness**: Guaranteed consistent results across agents
- **Cryptographic Attribution**: Verify AI contributions with mathematical certainty
- **Selective Integration**: Apply only the AI changes you trust

### Enterprise Production Workflows
- **Hotfix Automation**: Apply security fixes to all affected versions automatically
- **Audit Compliance**: Cryptographically verifiable change history
- **Attribution Intelligence**: Real-time AI contribution analytics
- **Mathematical Guarantees**: Provably correct operations

### Developer Experience
- **No Merge Conflicts**: Mathematical conflict resolution
- **Infinite Scalability**: O(n) complexity instead of O(n²)
- **Semantic Operations**: Work with meaning, not just files
- **Universal Operations**: Same commands work for changes and tags

## Project Structure

### Core Components
- **`atomic/`** - Main CLI application with commands for record, apply, push, pull
- **`libatomic/`** - Core VCS engine with mathematical patch operations
- **`atomic-macros/`** - Procedural macros for database operations
- **`atomic-config/`** - Configuration management with hierarchical loading

### Supporting Libraries
- **`atomic-identity/`** - Cryptographic identity and credential management
- **`atomic-interaction/`** - User interface and interaction patterns
- **`atomic-remote/`** - Remote repository operations (SSH, HTTP, Local)
- **`atomic-repository/`** - Repository management and working copy operations

### Development and Build
- **`contrib/`** - Additional resources and example configurations

## Key Features

- **Mathematical Soundness**: Based on theory of asynchronous work with formal guarantees
- **Cryptographic Security**: Merkle trees for integrity, signatures for attestation
- **AI Attestations**: First-class AI contribution tracking with verification
- **Distributed**: Fully distributed with no central authority required
- **Performance**: Sanakirja database backend optimized for VCS operations
- **Node Unification**: Changes and tags as unified graph nodes
- **Tag Consolidation**: O(n²) to O(n) dependency reduction

## ⚡ Watchman Integration for Lightning-Fast Recording

Atomic integrates with [Facebook's Watchman](https://facebook.github.io/watchman/) for dramatically faster `atomic record` operations on large repositories.

### Performance Results

| Repository Size | Without Watchman | With Watchman | Speedup |
|-----------------|------------------|---------------|---------|
| 100 files | 65ms | 71ms | ~1x (overhead dominates) |
| 10,000 files | 319ms | 68ms | **4.7x** |
| 50,000 files | 1,842ms | 69ms | **26.7x** |

**Key Insight**: Watchman query overhead is constant (~65ms) while full file scanning grows linearly with repository size. For large repositories, this translates to:
- **50K file repo**: Save 1.77 seconds per commit
- **100 commits/day**: Save 3+ minutes daily
- **Large monorepos**: 50-100x speedup possible

### How It Works

```
Without Watchman (O(n)):
  record() → Scan ALL 50,000 files → Compare each → 1,842ms

With Watchman (O(1)):
  record() → Query "what changed?" → Compare 5 files → 69ms
```

### Installation

#### 1. Install Watchman

```bash
# macOS
brew install watchman

# Ubuntu/Debian (from source or prebuilt)
# See: https://facebook.github.io/watchman/docs/install.html

# Verify installation
watchman version
```

#### 2. Build Atomic with Watchman Support

```bash
# Build with Watchman feature enabled
cargo build --release --features watchman

# Or install with Watchman support
cargo install --path atomic --features watchman
```

### Usage

When built with the `watchman` feature, Atomic automatically uses Watchman when available:

```bash
# Record changes (Watchman used automatically if available)
atomic record -m "My changes"

# Disable Watchman for a single command (force full scan)
atomic record -m "My changes" --no-watchman

# See Watchman status in logs
RUST_LOG=atomic=info atomic record -m "My changes"
```

**Output with Watchman:**
```
[INFO] Used Watchman for incremental change detection
Hash: ABCDEF123456...
```

### How Watchman State is Managed

Atomic stores Watchman clock state in `.atomic/watchman-state.json`:
- Clock tokens track "what changed since last record"
- State persists across commands for incremental queries
- Automatic fallback to full scan if Watchman unavailable

### When to Use Watchman

| Scenario | Recommendation |
|----------|----------------|
| Small repos (<500 files) | Optional - minimal benefit |
| Medium repos (500-5,000 files) | Recommended - 2-5x speedup |
| Large repos (5,000+ files) | Highly recommended - 10-30x speedup |
| Monorepos (50,000+ files) | Essential - 25-100x speedup |

For more details, see [docs/WATCHMAN-INTEGRATION.md](docs/WATCHMAN-INTEGRATION.md).

## Getting Started

### Installation

#### From Source
```bash
git clone https://github.com/atomicdotdev/atomic.git
cd atomic

# Standard build
cargo build --release --bin atomic --bin atomic-api

# Build with Watchman support (recommended for large repos)
cargo build --release --features watchman --bin atomic --bin atomic-api

sudo cp target/release/atomic /usr/local/bin/
sudo cp target/release/atomic-api /usr/local/bin/
```

#### Package Managers (Coming Soon!)
```bash
# macOS
brew install atomic

# Ubuntu/Debian
curl -fsSL https://beatomic.com/install.sh | sudo bash

# Arch Linux
yay -S atomic
```

### Basic Commands

#### Create a Repository
```bash
atomic init myproject
cd myproject
```

#### Track Files and Record Changes
```bash
# Add files to tracking
atomic add README.md src/main.rs

# Record a change (creates a patch)
atomic record -m "Initial implementation"

# Record with AI attestation
atomic record --ai-assisted --ai-provider openai -m "AI-generated documentation"
```

#### Create Consolidating Tags
```bash
# Create a consolidating tag (mathematical snapshot)
atomic tag create v1.0 -m "First release"

# Continue development with minimal dependencies
atomic record -m "Post-release feature"  # Depends only on TAG v1.0
```

#### View History and Attribution
```bash
# View change history
atomic log

# View AI attribution analysis
atomic attribution --stats --providers

# Verify cryptographic signatures
atomic verify --ai-attestations
```

#### Collaborate with Remotes
```bash
# Add remote repository
atomic remote add origin ssh://lee@beatomic.dev/user/portfolio/project/code

# Push changes and tags
atomic push origin

# Pull changes from remote
atomic pull origin
```

### Working with Stacks
Stacks provide filtered views of the DAG:

```bash
# Create feature channel
atomic stack new feature-auth

# Work on feature
atomic record -m "Add authentication" --stack feature-auth

# Apply to main
atomic apply --stack main <auth-changes>
```

### Mathematical Operations
```bash
# Apply changes in any order (commutativity)
atomic apply <change-1> <change-2>  # Same result as:
atomic apply <change-2> <change-1>

# Group dependencies (associativity)
atomic apply --group <tag-1> <changes>  # Same result as:
atomic apply <tag-1> && atomic apply <changes>

# Verify mathematical properties
atomic verify --mathematical-properties
```

## Advanced Features

### Cryptographic AI Attestation
```bash
# Configure AI attestation
export ATOMIC_AI_ENABLED=true
export ATOMIC_AI_PROVIDER=anthropic
export ATOMIC_AI_MODEL=claude-4.5

# All changes now include cryptographic attestation
atomic record -m "AI-assisted refactoring"

# Verify attestations
atomic verify --ai-attestations --provider anthropic
atomic attribution --confidence-analysis --cryptographic-proofs
```

### Production Hotfix Workflows
```bash
# Apply hotfix to historical tag and propagate
atomic hotfix --target-tag v1.0 --security-fix CVE-2024-1234
# Creates: v1.0.1, v1.1.1, v1.2.1, current-dev-patched

# Selective hotfix application
atomic hotfix --target-tag v2.0 --changes <change-hash> --propagate-to v2.1,v2.2
```

### Node-Based Operations
```bash
# Query any node type
atomic log                   # Works for changes OR tags
atomic change <hash>         # Shows dependencies for any node
atomic log --from <hash>     # History from any node

# Apply any node type
atomic apply <change-hash>   # Apply semantic patch
atomic apply <tag-hash>      # Apply consolidated snapshot
```

## Server Setup and Remote Connections

### Setting Up a Server

#### SSH Server Setup
```bash
# Install atomic on server
curl -fsSL https://beatomic.dev/install.sh | sudo bash

# Create bare repository
sudo atomic init --bare /var/lib/atomic/myrepo.atomic
sudo chown -R atomic:atomic /var/lib/atomic

# Configure SSH access
echo 'command="atomic serve /var/lib/atomic" ssh-rsa AAAAB...' >> ~/.ssh/authorized_keys
```

### Connecting to Remote Repositories

#### Configure Remote Repositories
```bash
# SSH remote
atomic remote add origin ssh://atomic@example.com/path/to/repo.atomic

# HTTP remote
atomic remote add origin https://atomic.example.com/api/repo

# HTTP with authentication
atomic remote add origin https://atomic.example.com/api/repo
atomic config set remote.origin.headers.Authorization "Bearer YOUR_TOKEN"
```

#### Working with Remotes
```bash
# Push changes and tags
atomic push origin

# Push specific changes
atomic push origin <change-hash>

# Push consolidating tags
atomic push origin --tags --consolidating

# Pull latest changes
atomic pull origin

# Pull specific tags
atomic pull origin --tag v1.0

# Clone repository
atomic clone ssh://git@example.com/repo.atomic myrepo
```

## Storage Architecture

### Database Structure
Atomic uses Sanakirja, a transactional key-value store optimized for VCS operations:

- **ACID Properties**: Full transaction support with rollback capability
- **Copy-on-Write**: Efficient storage with automatic deduplication
- **Concurrent Access**: Multiple readers with exclusive writer
- **Cryptographic Hashing**: Merkle trees for integrity verification

### Key Database Components
- **Changes**: Semantic patches with dependencies and hunks
- **Tags**: Consolidating snapshots with Merkle state proofs
- **Nodes**: Unified graph with change and tag nodes
- **Dependencies**: Mathematical dependency DAG
- **AI Attestations**: Cryptographic proofs of AI contributions
- **Attribution**: Detailed AI contribution analytics

### Performance Characteristics
- **O(1) Tag Lookups**: Consolidating tags provide constant-time access
- **O(n) Dependency Resolution**: Linear complexity instead of exponential
- **Parallel Operations**: Concurrent read access with lock-free data structures
- **Efficient Storage**: Content-addressed storage with automatic compression

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:

- Code style and formatting requirements
- Test coverage expectations
- Pull request process
- Mathematical correctness verification
- Cryptographic security review process

## License

Licensed under the GNU General Public License v2.0. See [LICENSE](LICENSE) for details.

## The Future of Version Control: Mathematical Guarantees + AI Intelligence

Atomic represents the next evolution of version control systems - one that provides **mathematical guarantees** for correctness while enabling **AI-scale development** with **cryptographic attestation**.

Traditional systems force developers to choose between semantic precision or scalability. Atomic's hybrid patch/snapshot model, unified node architecture, and tag consolidation eliminate this trade-off forever.

**Key Differentiators**:
- 🧮 **Mathematical Soundness**: Formally proven correctness properties
- 🔐 **Cryptographic Security**: Merkle trees and signature verification
- 🤖 **AI-Native Design**: First-class AI attestation and coordination
- 📈 **Infinite Scalability**: O(n) complexity with tag consolidation
- 🎯 **Enterprise Ready**: Audit compliance and production workflows

### Ready for Production

Atomic is ready for enterprise adoption with:
- ✅ **Mathematical Verification**: Formally verified correctness properties
- ✅ **Cryptographic Security**: Tamper-evident AI attestations
- ✅ **Performance Optimization**: Tag consolidation for O(n) complexity
- ✅ **Enterprise Features**: Audit trails, role-based access, compliance

## Acknowledgements

Built on the mathematical foundations of patch theory and distributed systems research. Special thanks to the Pijul project for pioneering patch-based version control and the research community advancing the theory of asynchronous work.

Atomic extends these foundations with cryptographic attestation for AI-native design workflows while maintaining mathematical correctness guarantees.

---

**Experience the future of version control. Try Atomic today.**

atomic-pijul

atomic-pijul 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

atomic-pijul

atomic-pijul 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README