[EPIC-3-1] vault: Implement vault directory structure and markdown utilities (Rust)

- What: Created complete vault filesystem utilities in Rust (sync-service)
- Why: Foundation for markdown-based knowledge storage (EPIC-3 File Vault System)
- How: 5 Rust modules using gray_matter, fs2, serde_yaml, sha2, tempfile

Modules implemented:
- template.rs: ItemMetadata struct + markdown template generation
- parser.rs: YAML frontmatter parsing (gray_matter crate)
- writer.rs: Atomic file operations (tempfile + rename)
- hash.rs: SHA-256 content hashing for change detection
- lock.rs: File locking with RAII pattern (fs2 crate)

Acceptance criteria addressed:
- [x] Vault module structure created (sync-service/src/vault/)
- [x] 5 modules implemented with public API
- [x] Dependencies added (gray_matter, fs2, uuid, chrono, tempfile)
- [x] Comprehensive documentation (docs/vault-structure.md)
- [x] 30 unit tests covering all modules
- [x] Coverage: 86.08% (exceeds 80% target)
- [x] Obsidian/VSCode compatibility (standard YAML frontmatter)
- [x] Atomic writes prevent partial file corruption
- [x] File locking prevents concurrent write conflicts

Testing:
- Unit tests: 30 passed, 1 ignored (multi-process lock timeout)
- Line coverage: 96.13%
- Region coverage: 86.08% (target: 80%+)
- All modules: hash (87.5%), lock (67.9%), parser (91.7%), template (100%), writer (87.4%)

Architecture:
- Vault utilities designed as reusable library (used by both sync-service and cli)
- All vault filesystem operations in Rust only (Python api-service never touches vault)
- RAII patterns for automatic cleanup (locks)
- Atomic file operations via tempfile (prevents race conditions)

Documentation:
- Complete vault structure guide (docs/vault-structure.md)
- Category descriptions (Inbox, People, Projects, Ideas, Admin)
- Frontmatter specification (required vs optional fields)
- File naming conventions and sanitization rules
- External tool compatibility notes (Obsidian, VSCode, Jekyll, Hugo)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: deserat

docs/dev/plans/EPIC-3-1-vault-markdown-utilities.md

@@ -3,6 +3,10 @@ name = "noosphere-sync"
 version = "0.1.0"
 edition = "2021"
 
+[lib]
+name = "noosphere_sync"
+path = "src/lib.rs"
+
 [[bin]]
 name = "noosphere-sync"
 path = "src/main.rs"
@@ -35,3 +39,19 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 
 # Configuration
 config = "0.14"
+
+# Vault Utilities
+# YAML frontmatter parsing
+gray_matter = "0.2"
+
+# File locking
+fs2 = "0.4"
+
+# UUID generation
+uuid = { version = "1.0", features = ["v4", "serde"] }
+
+# Timestamps
+chrono = { version = "0.4", features = ["serde"] }
+
+# Temporary files (atomic writes)
+tempfile = "3.0"

docs/vault-structure.md

@@ -0,0 +1,4 @@
+// Noosphere Sync Service Library
+// Provides reusable vault utilities for both sync-service and cli
+
+pub mod vault;

sync-service/Cargo.toml

@@ -0,0 +1,235 @@
+// Content hashing module for detecting file changes
+
+use anyhow::Result;
+use sha2::{Digest, Sha256};
+use std::fs;
+use std::path::Path;
+
+/// Compute SHA-256 hash of string content
+///
+/// Returns a hexadecimal string representation of the hash.
+/// Used for detecting content changes and sync conflict detection.
+///
+/// # Arguments
+///
+/// * `content` - The string content to hash
+///
+/// # Returns
+///
+/// A 64-character hexadecimal string (SHA-256 hash)
+///
+/// # Example
+///
+/// ```
+/// use noosphere_sync::vault::hash::compute_content_hash;
+///
+/// let hash1 = compute_content_hash("Hello, world!");
+/// let hash2 = compute_content_hash("Hello, world!");
+/// assert_eq!(hash1, hash2); // Same content = same hash
+///
+/// let hash3 = compute_content_hash("Different content");
+/// assert_ne!(hash1, hash3); // Different content = different hash
+/// ```
+pub fn compute_content_hash(content: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(content.as_bytes());
+    format!("{:x}", hasher.finalize())
+}
+
+/// Compute SHA-256 hash of a file's contents
+///
+/// Reads the entire file and computes its SHA-256 hash.
+/// Returns an error if the file cannot be read.
+///
+/// # Arguments
+///
+/// * `file_path` - Path to the file to hash
+///
+/// # Returns
+///
+/// A 64-character hexadecimal string (SHA-256 hash)
+///
+/// # Errors
+///
+/// Returns an error if:
+/// - File does not exist
+/// - File cannot be read
+/// - I/O error occurs
+///
+/// # Example
+///
+/// ```no_run
+/// use noosphere_sync::vault::hash::compute_file_hash;
+/// use std::path::Path;
+///
+/// let hash = compute_file_hash(Path::new("/tmp/test.md"))?;
+/// println!("File hash: {}", hash);
+/// # Ok::<(), anyhow::Error>(())
+/// ```
+pub fn compute_file_hash(file_path: &Path) -> Result<String> {
+    let content = fs::read(file_path)?;
+    let mut hasher = Sha256::new();
+    hasher.update(&content);
+    Ok(format!("{:x}", hasher.finalize()))
+}
+
+/// Check if file content has changed since cached hash
+///
+/// Compares the current file hash with a previously cached hash.
+/// Returns `true` if the content has changed (or if no cached hash provided).
+///
+/// # Arguments
+///
+/// * `file_path` - Path to the file to check
+/// * `cached_hash` - Optional previously computed hash
+///
+/// # Returns
+///
+/// - `true` if content has changed (or no cached hash available)
+/// - `false` if content is unchanged
+///
+/// # Errors
+///
+/// Returns an error if file cannot be read.
+///
+/// # Example
+///
+/// ```no_run
+/// use noosphere_sync::vault::hash::{compute_file_hash, has_content_changed};
+/// use std::path::Path;
+///
+/// let path = Path::new("/tmp/test.md");
+/// let cached = compute_file_hash(path)?;
+///
+/// // ... file is modified externally (e.g., in Obsidian) ...
+///
+/// if has_content_changed(path, Some(&cached))? {
+///     println!("File was modified externally!");
+/// }
+/// # Ok::<(), anyhow::Error>(())
+/// ```
+pub fn has_content_changed(file_path: &Path, cached_hash: Option<&str>) -> Result<bool> {
+    let current_hash = compute_file_hash(file_path)?;
+
+    match cached_hash {
+        Some(cached) => Ok(current_hash != cached),
+        None => Ok(true), // No cached hash, assume changed
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+    use tempfile::NamedTempFile;
+
+    #[test]
+    fn test_compute_content_hash() {
+        let content = "Hello, world!";
+        let hash = compute_content_hash(content);
+
+        // SHA-256 hash should be 64 hex characters
+        assert_eq!(hash.len(), 64);
+
+        // Hash should be deterministic
+        let hash2 = compute_content_hash(content);
+        assert_eq!(hash, hash2);
+    }
+
+    #[test]
+    fn test_hash_deterministic() {
+        let content = "Test content for hashing";
+        let hash1 = compute_content_hash(content);
+        let hash2 = compute_content_hash(content);
+        let hash3 = compute_content_hash(content);
+
+        assert_eq!(hash1, hash2);
+        assert_eq!(hash2, hash3);
+    }
+
+    #[test]
+    fn test_different_content_different_hash() {
+        let hash1 = compute_content_hash("Content A");
+        let hash2 = compute_content_hash("Content B");
+
+        assert_ne!(hash1, hash2);
+    }
+
+    #[test]
+    fn test_compute_file_hash() -> Result<()> {
+        // Create temporary file
+        let mut temp_file = NamedTempFile::new()?;
+        write!(temp_file, "Test file content")?;
+        temp_file.flush()?;
+
+        // Compute hash
+        let hash = compute_file_hash(temp_file.path())?;
+
+        // Should be 64 hex characters
+        assert_eq!(hash.len(), 64);
+
+        // Should match hash of content
+        let content_hash = compute_content_hash("Test file content");
+        assert_eq!(hash, content_hash);
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_has_content_changed_no_cache() -> Result<()> {
+        let mut temp_file = NamedTempFile::new()?;
+        write!(temp_file, "Initial content")?;
+        temp_file.flush()?;
+
+        // No cached hash - should report changed
+        assert!(has_content_changed(temp_file.path(), None)?);
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_has_content_changed_unchanged() -> Result<()> {
+        let mut temp_file = NamedTempFile::new()?;
+        write!(temp_file, "Static content")?;
+        temp_file.flush()?;
+
+        // Compute initial hash
+        let cached_hash = compute_file_hash(temp_file.path())?;
+
+        // Content hasn't changed
+        assert!(!has_content_changed(temp_file.path(), Some(&cached_hash))?);
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_has_content_changed_modified() -> Result<()> {
+        let mut temp_file = NamedTempFile::new()?;
+        write!(temp_file, "Initial content")?;
+        temp_file.flush()?;
+
+        // Compute initial hash
+        let cached_hash = compute_file_hash(temp_file.path())?;
+
+        // Modify file
+        temp_file.reopen()?;
+        write!(temp_file, "Modified content")?;
+        temp_file.flush()?;
+
+        // Content has changed
+        assert!(has_content_changed(temp_file.path(), Some(&cached_hash))?);
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_unicode_content() {
+        // Test with unicode characters
+        let content = "Hello, 世界! 🌍";
+        let hash1 = compute_content_hash(content);
+        let hash2 = compute_content_hash(content);
+
+        assert_eq!(hash1, hash2);
+        assert_eq!(hash1.len(), 64);
+    }
+}