Struct SourceFingerprint 

pub struct SourceFingerprint {
    pub main_len: u64,
    pub change_counter: Option<u32>,
    pub wal: Option<WalFileHeader>,
    pub wal_len: u64,
}

R858-B18 — everything about a source database’s files that must hold still for a copy of them to be a point-in-time image, sampled with no engine open and no lock taken.

This is the other half of reading a foreign-written database. A ReadOnly open (CoreWalSeam::open_reader) gets us in the door without stealing the whole-file lock, but it buys no shared locking protocol with upstream C SQLite: turso locks whole files with fcntl, C SQLite uses byte-range locks plus the -shm WAL index, and neither engine observes the other’s. So a foreign checkpoint landing in the middle of our copy can fold WAL frames into the main file we have already half-read, and the result is a torn image that still passes PRAGMA integrity_check.

Rather than reimplement SQLite’s reader protocol (registering a read-mark in the -shm WAL index — a research project and a permanent compatibility liability against an engine we do not control), raw_consistent_copy_live uses textbook optimistic validation: sample this before the copy, sample it again after, and accept the copy only if nothing moved. That converts “may silently read torn state” into “detects torn state and refuses”, needs no cooperation from the foreign engine, and costs two stats and a 132-byte read per attempt.

Why these fields

• wal (salt + checkpoint_seq) moves on every WAL reset, in both fold regimes — fresh randomness on a writer restart, salt1 incrementing on an in-process autocheckpoint (both measured; see WalSalt).
• main_len moves when a checkpoint grows the main database.
• change_counter (main header bytes 24..28) moves on every write to the main file — i.e. on every checkpoint — even one that leaves its length alone. It is meaningful here only because the foreign writer is C SQLite: turso does not maintain this field (it stays 1 in every journal mode, verified — see snapshot.rs’s two-gate rationale), which is exactly why the WAL salt carries the weight and this one is corroboration.
• wal_len is recorded for the report but deliberately not part of the accept/reject test — see Self::stable_across, which is the comparison to use. There is no PartialEq on this type on purpose: a bare == would silently include wal_len and refuse every copy taken while the application was merely writing.

Fields

main_len: u64

Length of the main database file.

change_counter: Option<u32>

The main header’s change counter, or None when the file is too short to carry a SQLite header at all (a database whose page 1 still lives only in the WAL). Unknown-and-unknown compares equal, which is safe because main_len participates in the same comparison.

wal: Option<WalFileHeader>

The -wal header, or None when there is no WAL sidecar.

wal_len: u64

Length of the -wal file (0 when absent).

Implementations

impl SourceFingerprint

pub fn read(db_path: &str) -> Result<Self>

Sample the fingerprint of the database at db_path. Touches nothing: two metadata calls plus a 28-byte and a 32-byte read.

pub fn stable_across(&self, after: &Self) -> bool

True when nothing that can tear a copy moved between self (sampled before) and after (sampled after). This is the accept test in raw_consistent_copy_live, and it is narrower than field equality on purpose.

What can tear the copy, and what cannot

The copy reads the main file, then replays WAL frames 1..=max_frame captured when the seam opened. Against that algorithm:

• A checkpoint tears it. It rewrites pages of the main file and resets the WAL, so our already-read main bytes and our frame reads can straddle the fold — replaying pre-fold frames over post-fold pages rolls pages backwards. Caught: a checkpoint bumps change_counter and/or main_len, and a WAL restart re-rolls the salt and the sequence (measured in both regimes, examples/foreign_checkpoint_probe.rs probes A and E).
• A plain append does NOT tear it. SQLite only ever appends frames within a generation, and only a reset (which re-rolls salt1) lets it overwrite an existing frame. So frames 1..=max_frame are immutable for as long as the salt holds, and a writer that commits during our copy just means our image is a slightly earlier point in time — which is what a point-in-time copy is.

Which is why wal_len and the frame count are excluded. Including them buys no additional safety and costs a refusal on every copy taken while the application is writing at all — turning a working backup into one that only succeeds against an idle database. R858-B18 measured that difference rather than assuming it; see probe H.

Trait Implementations

impl Clone for SourceFingerprint

fn clone(&self) -> SourceFingerprint

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for SourceFingerprint

impl Debug for SourceFingerprint

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.