Clarify the sync consistency model and concurrent file modification semantics

cmdline/sync.c

@@ -11,6 +11,96 @@
 #include "io.h"
 #include "raid/raid.h"
 
+/*
+ * SnapRAID sync model
+ *
+ * The sync operation brings the stored parity and content metadata in line
+ * with the state of the data files observed by SnapRAID.
+ *
+ * On the first sync, there is no previously synchronized state for the data
+ * files. SnapRAID scans the filesystem, allocates parity blocks for the files,
+ * reads their data, computes the corresponding hashes, and generates parity.
+ * The resulting content file records the file metadata and block hashes that
+ * describe the synchronized state.
+ *
+ * On subsequent syncs, SnapRAID scans the filesystem again and compares the
+ * current files with the state recorded by the previous sync. Files that are
+ * added, removed, moved, restored, or changed are identified from their
+ * metadata and only the affected parity state has to be updated. Files that
+ * are still considered unchanged can continue to use their previously
+ * synchronized hashes and parity.
+ *
+ * The content file and the parity represent two related but distinct parts
+ * of the synchronized state. The content file records SnapRAID's logical
+ * knowledge of the array, including file metadata, block allocation, hashes,
+ * and the state of each block. The parity files contain the parity data
+ * physically generated from the data blocks.
+ *
+ * These two states cannot always be assumed to advance atomically. In
+ * particular, if a sync is interrupted, some parity blocks may already have
+ * been updated while the corresponding new logical state has not yet been
+ * committed to the content file, or vice versa for intermediate block states.
+ * The CHG, REP, BLK, and related block states are used to preserve enough
+ * information to reason about these intermediate conditions and to complete
+ * or recover safely on a later operation.
+ *
+ * Therefore, when analyzing sync correctness, the state recorded in the
+ * content file must not be interpreted as an unconditional statement that
+ * every corresponding parity block has already been physically updated to
+ * exactly that state. The sync logic explicitly accounts for interrupted
+ * operations and for the possible difference between the last committed
+ * logical state and the actual parity state on disk.
+ *
+ * SnapRAID is not a real-time RAID system. A successful sync establishes a
+ * synchronized point in the history of the filesystem, but it does not make
+ * the data files immutable after that point. Files may be modified at any
+ * time before, during, or after the sync.
+ *
+ * In particular, when operating on a live writable filesystem, sync does not
+ * require every file to remain unchanged for the whole duration of the
+ * command and does not attempt to provide a transactional or atomic view of
+ * all files.
+ *
+ * A file may therefore change while it is being processed. Such a change is
+ * conceptually handled in the same way as a change made immediately after
+ * that file has been synchronized. The parity generated by the current sync
+ * may then temporarily describe an older or intermediate state of that file,
+ * while the live filesystem already contains a newer state.
+ *
+ * This is expected. Parity temporarily not matching the current live contents
+ * of a file that has been modified during or after sync is not, by itself, an
+ * indication of parity corruption or a sync correctness failure. SnapRAID
+ * parity is expected to become outdated whenever synchronized files are later
+ * modified, and a subsequent sync brings it up to date again.
+ *
+ * Consequently, a modification occurring while a file is being read does not
+ * have to be detected by that same sync in order to preserve the normal
+ * SnapRAID consistency model. If the resulting file differs in metadata used
+ * for change detection, such as size or modification time, a subsequent scan
+ * will identify it as changed and the next sync will process it again.
+ *
+ * The same principle applies to races occurring around file access. For
+ * example, a write after a file has been opened, a write between two block
+ * reads, or a replacement immediately before or after the last block is read
+ * has the same consistency implications as modifying the file immediately
+ * after it was synchronized: the current parity may become outdated, and the
+ * later change is handled by a subsequent sync.
+ *
+ * The metadata checks performed while sync is running are therefore not a
+ * mechanism intended to keep the filesystem transactionally frozen or to
+ * detect every concurrent modification. They provide additional detection
+ * for changes that are already observable at the points where those checks
+ * are made.
+ *
+ * This model relies on later modifications being visible to SnapRAID's normal
+ * change-detection mechanism. A content modification that preserves all
+ * metadata relevant to change detection may not be recognized by a later
+ * scan. A typical example is an in-place modification that preserves both
+ * file size and modification time. This is a separate, documented limitation
+ * of metadata-based change detection and is not specific to modifications
+ * occurring concurrently with sync.
+ */
+
 /****************************************************************************/
 /* hash */