Crate turbovault_batch 

Batch Operations Framework

Provides validated, fail-fast batches of vault file operations. Individual mutations use VaultManager atomic file operations, but a batch is not an all-or-nothing transaction: operations completed before a failure remain applied and are reported in BatchResult.

Quick Start

use turbovault_core::ServerConfig;
use turbovault_vault::VaultManager;
use turbovault_batch::BatchExecutor;
use turbovault_batch::BatchOperation;
use std::sync::Arc;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ServerConfig::default();
    let manager = VaultManager::new(config)?;
    let executor = BatchExecutor::from_manager(Arc::new(manager));

    // Define batch operations
    let operations = vec![
        BatchOperation::CreateNote {
            path: "notes/new1.md".to_string(),
            content: "# First Note".to_string(),
            force: None,
        },
        BatchOperation::CreateNote {
            path: "notes/new2.md".to_string(),
            content: "# Second Note".to_string(),
            force: None,
        },
        BatchOperation::UpdateLinks {
            file: "notes/index.md".to_string(),
            old_target: "old-link".to_string(),
            new_target: "new-link".to_string(),
            expected_hash: None,
        },
    ];

    // Execute sequentially, stopping at the first failure
    let result = executor.execute(operations).await?;
    println!("Success: {}", result.success);
    println!("Changes: {}", result.changes.len());

    Ok(())
}

Core Types

BatchOperation

Individual operations to execute in a batch:

• BatchOperation::CreateNote - Create a new note
• BatchOperation::WriteNote - Write or overwrite a note
• BatchOperation::DeleteNote - Delete a note
• BatchOperation::MoveNote - Move or rename a note
• BatchOperation::UpdateLinks - Update link references

BatchExecutor

BatchExecutor manages batch execution with:

• Validation before execution
• Conflict detection between operations
• Sequential, fail-fast execution with proper ordering
• Transaction ID tracking
• Detailed result reporting

BatchResult

BatchResult contains execution results:

• Overall success/failure status
• Count of executed operations
• First failure point (if any)
• List of changes made
• List of errors encountered
• Individual operation records
• Unique transaction ID
• Execution duration

Conflict Detection

Operations that affect the same files are detected as conflicts:

• Write + Delete on same file = conflict
• Move + Write on same file = conflict
• Multiple reads (UpdateLinks) = allowed

Example:

use turbovault_batch::BatchOperation;

let write = BatchOperation::WriteNote {
    path: "file.md".to_string(),
    content: "content".to_string(),
    expected_hash: None,
};

let delete = BatchOperation::DeleteNote {
    path: "file.md".to_string(),
    expected_hash: None,
    on_backlinks: None,
};

assert!(write.conflicts_with(&delete));

Execution Guarantees

The batch executor ensures:

• The batch is validated for conflicting operations before execution
• Execution stops at the first operation failure
• Transaction tracking with unique IDs
• Execution timing recorded
• Detailed per-operation records for debugging
• Each individual file write uses the vault manager’s atomic write path

Error Handling

Errors stop batch execution:

• Validation errors prevent any execution
• Operation errors stop the batch
• Previous operations are recorded but not rolled back
• Error details provided in result

If true rollback is needed, handle externally using transaction IDs.

Performance

Batch execution is optimized for:

• Minimal validation overhead
• Sequential execution with early termination
• Efficient conflict checking (O(n²) upfront)
• Low-overhead operation tracking

Structs

BatchExecutor

Batch executor with validation, sequencing, and transaction identifiers.

BatchResult

Result of batch execution

OperationRecord

Record of a single executed operation

Enums

BatchOperation

Individual batch operation to execute