darn_core

Core library for darn - CRDT-backed filesystem management.

Overview

darn_core provides the foundational types and logic for managing files as Automerge CRDT documents. It handles:

Feature	Description
Workspace management	`.darn` marker file and centralized storage
File-to-document mapping	Converting files to/from Automerge documents
Manifest tracking	Mapping file paths to Sedimentree IDs
Change detection	BLAKE3 content hashing for efficient diffing
Ignore patterns	Gitignore-style patterns stored in `.darn` config
Directory tree sync	Patchwork-style directory structure as Automerge docs
Staged batch writes	Two-phase commit for atomic workspace updates

Architecture

Module	Purpose
`darn.rs`	Workspace management + sync methods
`file.rs`	File ↔ Automerge conversion
`directory.rs`	Directory tree (Patchwork-style)
`manifest.rs`	`Tracked`, `ContentHash`, `FileState`
`dotfile.rs`	`.darn` config file (JSON)
`ignore.rs`	Ignore pattern matching
`staged_update.rs`	Two-phase batch file writes
`refresh.rs`	Change detection & incremental sync
`peer.rs`	Peer config (JSON)
`signer.rs`	Ed25519 key management
`config.rs`	Global config (`~/.config/darn/`)
`watcher.rs`	Filesystem watcher for auto-sync

Key Types

Darn

Workspace management and sync orchestration:

use darn_core::darn::Darn;

// Initialize new workspace
let ws = Darn::init(Path::new("my-project"))?;

// Open existing
let darn = Darn::open(Path::new("my-project")).await?;

// Access components
let manifest = darn.load_manifest()?;
let subduction = darn.subduction();

File

Patchwork-compatible file representation:

use darn_core::file::{File, content::Content};

// Create from file
let doc = File::from_path("example.txt")?;

// Or construct directly
let doc = File::text("notes.txt", "Hello, world!");

// Convert to Automerge
let mut am_doc = doc.to_automerge()?;
let bytes = am_doc.save();

`Tracked` & `FileState`

Track files with change detection:

use darn_core::manifest::tracked::{Tracked, FileState};

// Check file state
match entry.state(workspace_root) {
    FileState::Clean => println!("unchanged"),
    FileState::Modified => println!("changed on disk"),
    FileState::Missing => println!("deleted"),
}

File Document Schema

Patchwork-inspired schema:

Field	Type	Description
`name`	`Name`	Validated filename (no path seps)
`content`	`Text` or `Bytes`	File content
`metadata`	`Metadata`	Permissions (u32, rwx display)

Content encoding:

Text files → Text object (character-level CRDT merging)
Binary files → Bytes scalar (last-writer-wins)

Serialization

Data	Format	Notes
File documents	Automerge	Direct API (`put`, `get`), not serde
Manifest	JSON	Via `serde_json`, base58 for 32-byte types
Peer config	JSON	One file per peer in `~/.config/darn/peers/`
Sedimentree data	CBOR	Via `minicbor`, managed by Subduction

File documents use Automerge's direct API rather than serde integration. This gives explicit control over CRDT types (e.g., ObjType::Text for character-level merging vs ScalarValue::Bytes for LWW semantics).

Dependencies

Crate	Purpose
`automerge`	CRDT document storage
`sedimentree_core`	Content-addressed partitioning
`sedimentree_fs`	Filesystem storage backend
`subduction_core`	Sync protocol
`blake3`	Content hashing
`serde` / `serde_json`	JSON serialization

License

Apache-2.0 OR MIT

darn_core 0.4.0