# What Are the Guarantees of the Claude-Obsidian Transaction System?

> Discover the guarantees of the claude-obsidian transaction system: atomic, recoverable, and isolated operations. Learn about its features ensuring vault consistency.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: deep-dive
- Published: 2026-08-29

---

**The claude-obsidian transaction system provides atomic, recoverable, and isolated operations with deterministic size limits, pre-flight validation, and dry-run capabilities to ensure vault consistency.**

Every knowledge-changing operation in the AgriciDaniel/claude-obsidian repository is treated as a single, recoverable transaction. The system wraps vault modifications in a structured bundle format that enforces strict safety guarantees before any file mutation occurs. Understanding these guarantees is essential for maintaining consistent, corruption-free Obsidian vaults during automated operations.

## Core Transaction Guarantees

### Atomicity (All-or-Nothing Writes)

The transaction engine ensures **atomicity** by writing a transaction bundle using the `claude-obsidian.transaction.v1` format. In [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py), the engine pre-flights the entire operation list against the journal before modifying any files. If any step fails validation, the system aborts the entire transaction, ensuring that partial writes never corrupt the vault state.

### Recoverability via Journal Replay

The system maintains a persistent **journal** of every pending operation, enabling full recovery from interruptions. According to the source code in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py), users can replay interrupted transactions using the `transaction recover` CLI command. This reads the journal and restores the vault to a consistent state without manual intervention.

### Deterministic Size Limits

To prevent resource exhaustion, the engine enforces strict boundaries: each transaction file is limited to **64 MiB**, and a single bundle may contain at most **1,024 writes**. These limits are validated in [`claude_obsidian/contracts.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/contracts.py) before the transaction engine applies any changes, protecting against runaway operations.

### Pre-Flight Validation

Before committing changes, the system performs **pre-flight validation** by checking expected SHA-256 hashes and other invariants against the current vault state. This verification happens in the core transaction logic, rejecting bundles that would violate consistency constraints or overwrite unexpected content.

### Dry-Run and Preview Mode

Users can inspect proposed changes without risk using the `--dry-run` flag. When invoked via [`scripts/claude-obsidian.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/claude-obsidian.py), this mode renders the transaction bundle's effects without mutating the filesystem, allowing reviewers to approve or reject operations before permanent application.

### Idempotency and Deterministic Ordering

All writes are ordered by the transaction's internal ledger, with duplicate operations automatically collapsed. As implemented in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py), this guarantees that re-applying the same bundle produces identical results without side effects, making recovery operations safe and predictable.

### Isolation from the Host Filesystem

The transaction system acts as the sole mediator for all vault modifications. Even high-level operations like `init`, `adopt`, `migrate`, `capture apply`, and `mode set` are routed through the transaction core in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py). Direct filesystem writes are refused, ensuring that all changes pass through the validation and journaling pipeline.

### Safety on Unsupported Platforms

On platforms where atomicity cannot be guaranteed—such as Windows WSL in certain configurations—the system returns an `UNSUPPORTED_PLATFORM` error rather than risk corruption. This safeguard, documented in the Compound Vault Guide, ensures that the engine only operates where it can enforce its full guarantee set.

## Working with Transactions: Practical Examples

The CLI and Python API provide interfaces for applying, previewing, and recovering transactions.

Applying a prepared bundle:

```bash
python3 scripts/claude-obsidian.py transaction apply \
    --vault /path/to/vault \
    --bundle path/to/your-transaction.json

```

Previewing changes with dry-run:

```bash
python3 scripts/claude-obsidian.py transaction apply \
    --vault /path/to/vault \
    --bundle path/to/your-transaction.json \
    --dry-run

```

Recovering an interrupted transaction:

```bash
python3 scripts/claude-obsidian.py transaction recover \
    --vault /path/to/vault

```

Creating transactions programmatically:

```python
from claude_obsidian.transaction import TransactionBundle, TransactionOperation

# Build a simple bundle that creates a page

bundle = TransactionBundle(
    version="claude-obsidian.transaction.v1",
    operations=[
        TransactionOperation(
            op="write",
            path="wiki/example.md",
            content="# Example Page\nContent here.\n"

        )
    ]
)

# Serialize to JSON and feed to the CLI or the internal apply API

bundle_json = bundle.to_json()
print(bundle_json)

```

## Key Implementation Files

The guarantee set is implemented across several core modules:

- **[`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py)**: Defines the bundle format, applies operations, performs pre-flight checks, and handles recovery logic.
- **[`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py)**: Maintains the journal and ledger entries that record every write for recoverability and ordering.
- **[`claude_obsidian/contracts.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/contracts.py)**: Declares the contract schema and validates incoming bundles against size limits and structural constraints.
- **[`scripts/claude-obsidian.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/claude-obsidian.py)**: CLI entry point that parses commands such as `transaction apply` and `recover`, forwarding them to the transaction core.
- **[`docs/compound-vault-guide.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/compound-vault-guide.md)**: Documents the transaction model, atomicity guarantees, size limits, and recovery workflows.
- **[`docs/methodology-modes-guide.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/methodology-modes-guide.md)**: Explains how configuration changes are wrapped in transactions and previewed safely.

## Summary

- **Atomicity**: Transactions use the `claude-obsidian.transaction.v1` bundle format with pre-flight validation to ensure all writes succeed or none are applied.
- **Recoverability**: The journal system supports replay via `transaction recover` to restore consistent state after interruptions.
- **Safety Limits**: Hard caps of 64 MiB per file and 1,024 writes per bundle prevent resource exhaustion.
- **Validation**: Pre-flight checks verify SHA-256 hashes and invariants before any filesystem mutation.
- **Preview Capability**: The `--dry-run` flag allows inspection of changes without applying them.
- **Idempotency**: Deterministic ordering and duplicate collapse ensure safe re-application of transaction bundles.
- **Platform Safety**: The system refuses operations with `UNSUPPORTED_PLATFORM` errors when atomicity cannot be guaranteed.

## Frequently Asked Questions

### What happens if a transaction is interrupted mid-write?

The system maintains a persistent journal in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) that records every pending operation. If a crash or interruption occurs, you can run `python3 scripts/claude-obsidian.py transaction recover --vault /path/to/vault` to replay the journal and restore the vault to a consistent state.

### How can I preview changes before applying them to my vault?

Use the `--dry-run` flag when invoking `transaction apply`. This mode renders the proposed changes from the bundle without mutating any files, allowing you to review the effects before committing.

### What are the size limits for claude-obsidian transactions?

Each transaction file is limited to 64 MiB, and a single bundle may contain at most 1,024 write operations. These limits are enforced by the contract validator in [`claude_obsidian/contracts.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/contracts.py) to prevent runaway transactions.

### Does claude-obsidian work on all operating systems?

The system includes safeguards that refuse writes on platforms where atomic guarantees cannot be met, such as certain Windows WSL configurations. In these cases, it returns an `UNSUPPORTED_PLATFORM` error rather than risk vault corruption.