Module Layout

chronicle/
├── src/
│   ├── bin/chronicle.rs       # CLI entry point
│   ├── lib.rs                 # Library root (public API)
│   ├── fuser_filesystem.rs    # FUSE backend (macFUSE/libfuse)
│   ├── fskit_filesystem.rs    # FSKit backend (macOS 26+, no macFUSE)
│   ├── cas.rs                 # Content-Addressable Store (BLAKE3, chunking, layers)
│   ├── iteration.rs           # Iteration (version) management
│   ├── metadata_cache.rs      # In-memory metadata cache (DashMap)
│   ├── types.rs               # FileMetadata, IterationInfo
│   ├── errors.rs              # Error types
│   ├── cache.rs               # Read caching
│   ├── metrics.rs             # Performance metrics
│   ├── sync_database.rs       # SQLite database abstraction
│   ├── protocol.rs            # Magic file API (.chronicle/query/*)
│   ├── storage/
│   │   ├── local.rs           # LocalFileCAS (filesystem-backed)
│   │   ├── s3.rs              # S3CAS (cloud-backed)
│   │   ├── socket_cas.rs      # SocketCAS (CAS over replication socket)
│   │   ├── tiered.rs          # TieredCAS (local + S3 with promotion)
│   │   └── traits.rs          # ContentStorage trait
│   ├── replication/
│   │   ├── push_manager.rs    # Push notifications (agent → sandbox)
│   │   ├── receiver.rs        # Receive notifications (sandbox side)
│   │   ├── reconcile.rs       # Reconciliation engine
│   │   ├── socket_transport.rs # Wire protocol (bincode over Unix socket)
│   │   ├── ws_transport.rs    # WebSocket transport (for E2B sandboxes)
│   │   ├── journal.rs         # Write-back journal (sandbox → agent)
│   │   ├── writeback_loop.rs  # Write-back processing
│   │   ├── filter.rs          # Gitignore-compatible sync filtering
│   │   ├── content_fetcher.rs # Large file fetch over replication
│   │   └── notifier.rs        # File change notifications
│   └── platform/
│       └── macos.rs           # macOS version detection, FSKit availability
└── Cargo.toml

Database Schema

Chronicle uses SQLite with WAL mode for metadata:

files table

ColumnTypeDescription
inodeINTEGER PKFUSE inode number
parent_inodeINTEGERParent directory inode
nameTEXTFilename
is_dirBOOLEANDirectory flag
sizeINTEGERFile size in bytes
permissionsINTEGERPOSIX permissions
content_hashTEXTBLAKE3 hash of current content
created_atTEXTCreation timestamp
modified_atTEXTLast modification timestamp
iterationINTEGERCurrent iteration number

iterations table

ColumnTypeDescription
rowidINTEGER PKMonotonically increasing sequence
inodeINTEGER FKFile inode
iterationINTEGERIteration number for this file
content_hashTEXTBLAKE3 hash at this iteration
sizeINTEGERFile size at this iteration
permissionsINTEGERPermissions at this iteration
timestampTEXTWhen this iteration was created
is_deletionBOOLEANWhether this iteration is a deletion marker

Feature Flags

FeatureDefaultDescription
fuse-backendYesStandard FUSE via fuser crate (requires macFUSE/libfuse)
fskit-backendNomacOS FSKit backend preference (auto-detect on macOS 15.4+)
native-fskitNoCompile-time FSKit backend via fskit-rs (no macFUSE needed)
Build without macFUSE:
cargo build --no-default-features --features native-fskit