Skip to main content

Crate turbovault_vault

Crate turbovault_vault 

Source
Expand description

§Vault Manager

Vault operations, file watching, and atomic operations.

This crate provides the core vault management functionality including:

  • File reading and writing with error handling
  • Real-time file system watching
  • Atomic operations with transaction support
  • Edit engine for advanced file modifications
  • Diff-based updates with fuzzy matching

§Quick Start

use turbovault_vault::VaultManager;
use turbovault_core::ServerConfig;
use std::path::PathBuf;

// Create a vault manager
let config = ServerConfig::default();
let manager = VaultManager::new(config)?;

// Read a file
let path = PathBuf::from("notes/example.md");
let _vault_path = manager.vault_path();

§Core Modules

§Manager

manager::VaultManager is the primary interface for vault operations:

  • Read/write files
  • Query metadata
  • List files
  • Traverse directory structure

§File Watching

watcher::VaultWatcher monitors the vault for changes:

  • File creates, modifies, deletes
  • Directory changes
  • Debounced events
  • Configurable filtering

Example:

use turbovault_vault::WatcherConfig;

let _config = WatcherConfig::default();
// Watcher runs in background, emit events via channel

§Atomic Operations

atomic::AtomicFileOps ensures data integrity:

  • Atomic writes (write-to-temp then rename)
  • Transaction support
  • Rollback on failure

§Edit Engine

edit::EditEngine provides advanced editing capabilities:

  • Search and replace with context
  • Block-based edits
  • Diff-based fuzzy matching
  • Hash verification

Example:

use turbovault_vault::EditEngine;

let _edit_engine = EditEngine::new();
// Use edit_engine for advanced file modifications

§Thread Safety

All components are thread-safe:

  • VaultManager uses Arc<RwLock<...>> internally
  • Safe to share across async tasks
  • Concurrent read access with exclusive write access

§Error Handling

All operations return turbovault_core::Result<T>:

  • File not found errors
  • Permission errors
  • Invalid paths
  • Encoding errors
  • Atomicity violations

Re-exports§

pub use atomic::AtomicFileOps;
pub use atomic::FileOp;
pub use atomic::TransactionResult;
pub use edit::EditEngine;
pub use edit::EditResult;
pub use edit::SearchReplaceBlock;
pub use edit::compute_hash;
pub use manager::ChangeListener;
pub use manager::ScannedNote;
pub use manager::VaultManager;
pub use reindex::CommitOrigin;
pub use reindex::PendingCommit;
pub use reindex::ReindexQueue;
pub use reindex::apply_commit_diff;
pub use reindex::watch_ref_changes;
pub use substrate::ApplyOutcome;
pub use substrate::DirectSubstrate;
pub use substrate::GitSubstrate;
pub use substrate::WriteSubstrate;
pub use watcher::VaultEvent;
pub use watcher::VaultWatcher;
pub use watcher::WatcherConfig;

Modules§

atomic
Atomic file operations with rollback support.
edit
LLM-optimized file editing with SEARCH/REPLACE blocks
manager
Vault manager implementation with file watching and caching
prelude
reindex
Lazy GSU (Graph + Search Update) queue + apply (GWS.14).
substrate
WriteSubstrate — the dispatch point behind VaultManager (write- substrate-layering M3a, turbovault-qae.4.1).
watcher
File system watcher for vault changes.

Structs§

Block
A block in vault content (Obsidian block reference with ^id)
Callout
A callout block in vault content
Citation
A citation backing a claim in a concept body (spec §8).
CompositeValidator
Composite validator that runs multiple validators
ConceptConformance
Per-document OKF conformance result (spec §9).
ContentValidator
Validates file content structure
Counter
A lock-free counter metric (monotonically increasing)
FileMetadata
File metadata
Frontmatter
YAML frontmatter
FrontmatterValidator
Validates frontmatter structure and required fields
Heading
A heading in vault content
Histogram
A histogram for tracking value distributions
LineIndex
Pre-computed line starts for O(log n) line/column lookup.
Link
A link in vault content
LinkValidator
Validates link syntax and format
ListItem
A list item with optional checkbox and nested content.
MetricsContext
Global metrics context registry (rarely used)
MultiVaultManager
Multi-vault manager coordinating multiple vaults
ServerConfig
Global server configuration
SourcePosition
Position in source text (line, column, byte offset)
Tag
A tag in vault content
TaskItem
A task item in vault content
ValidationIssue
A validation issue found in content
ValidationReport
Result of validating content
VaultConfig
Configuration for a single vault
VaultFile
A complete vault file with parsed content
VaultInfo
Information about a registered vault
WriteAttribution
Who the host believes performed a write.

Enums§

CalloutType
Type of callout block
ConfigProfile
Profile selector for pre-configured deployments
ContentBlock
A parsed content block in a markdown document.
Error
The core error type for all Obsidian operations.
InlineElement
An inline element within a block.
LinkType
Type of link in Obsidian content
ReservedFile
A reserved OKF filename with defined meaning at any level of the hierarchy.
Severity
Severity level for validation issues
TableAlignment
Table column alignment.
VaultChange
A single observed vault mutation.

Traits§

Validator
Trait for content validators
VaultEventSink
Receives vault changes as the write and observation paths report them.

Functions§

check_concept
Check a single document for OKF v0.1 conformance (§9).
concept_id
Compute the OKF concept ID for a document: its path within the bundle with the .md suffix removed and / separators.

Type Aliases§

Result
Convenient Result type alias