Safety and backups

Code Folder Sync is designed for a small trusted fleet. It preserves observed stable versions and fails closed when the evidence required for safe capture, ordering, or apply is unavailable.

Trust model

There is no multi-user authorization layer, hosted API, or peer-to-peer leader election in Version 2.

Filesystem boundary

• The configured root cannot be a symlink.
• Every apply path is normalized, contained, and checked through real directory ancestors.
• Capture uses lstat; symlink target text is stored without dereferencing.
• Sockets, devices, FIFOs, unsafe aliases, and external Git-directory indirection stop affected work.
• Bytes, directory structure, executable meaning, and symlink targets are portable.

Ownership, ACLs, extended attributes, non-executable permission bits, timestamps, sparse allocation, flags, and hardlink topology are not preserved.

Durability

Local and hub SQLite stores use WAL and full synchronous commits. Objects commit before any event can expose them. Local mutations enter a durable outbox before network I/O. Remote replacements move existing content to recovery and use journaled atomic rename instead of unlinking the only live bytes first.

Retention

Current state, accepted event history, conflicts, recovery data, and their immutable objects are retained. Garbage collection is report-only:

codefoldersync gc --dry-run

Automatic deletion is disabled.

Backup and restore

A complete backup includes all four parts:

1. The synchronized root.
2. The complete peer state directory.
3. The owner-only folder configuration.
4. The whole hub directory, including both SQLite stores and a consistent view of WAL state.

Stop hub writers or use a storage-level consistent snapshot. After a restore, keep normal writers stopped and run doctor,status, verify --full, andgit fsck --full before resuming the daemon.