Snapshot: the manifest is a stat cache; unchanged opaque files are not read and contribute their recorded blob, with a two-second racy-stat window (status on 1 GiB 2.4 s to 4 ms; spec 0.6s) b7f102fcbb17

        let blobs: HashMap<String, ObjectRef> = target

            .files

            .iter()

            .filter_map(|(p, f)| match &f.content {

                FileContent::Opaque { blobs } if f.kind == NodeKind::File && blobs.len() == 1 => Some((p.clone(), blobs[0])),

                _ => None,

            })

            .collect();

        let entries = self.walk_working_copy()?;

        self.write_manifest_entries(report.conflicted, false, &entries, &blobs)?;

                entries.insert(path, FsEntry::new(kind, exec, content));

                out.insert(p.clone(), FsEntry::new(src.kind, src.mode.exec, content));

    /// File content, or a symlink's target. Empty when `blob` is set.

    /// The stored blob of an opaque file whose size and mtime are unchanged

    /// since the last manifest (spec §12.3 stat cache); the content was not

    /// read.

    pub blob: Option<ObjectRef>,

    /// BLAKE3 of the content, carried over from the manifest when the stat

    /// is unchanged, so the manifest can be rewritten without rehashing.

    pub content_hash: Option<String>,

impl FsEntry {

    pub(crate) fn new(kind: NodeKind, exec: bool, content: Vec<u8>) -> FsEntry {

        FsEntry { kind, exec, content, blob: None, content_hash: None }

    }

}

        self.walk_working_copy_with(None)

    }

    /// Walk the working copy; with a manifest, a file whose size and mtime

    /// match it is not read: an opaque file yields its known blob, a text

    /// file is read but keeps its known hash. Files modified within two

    /// seconds of the manifest are never trusted (a racy stat).

    fn walk_working_copy_with(&self, cache: Option<&prompt::Manifest>) -> Result<BTreeMap<String, FsEntry>> {

                out.insert(rel, FsEntry::new(NodeKind::Symlink, false, target.to_string_lossy().as_bytes().to_vec()));

                let meta = entry.metadata().map_err(|e| RepoError::Msg(e.to_string()))?;

                let exec = is_executable(&meta);

                let cached = cache.and_then(|m| {

                    let e = m.entries.get(&rel)?;

                    let mtime_ns = prompt::mtime_ns(&meta);

                    let racy = mtime_ns + 2_000_000_000 >= m.written_ns;

                    (e.size == meta.len() && e.mtime_ns == mtime_ns && !racy).then_some(e)

                });

                match cached {

                    Some(e) if e.blob.is_some_and(|b| self.store.has(&b)) => {

                        out.insert(rel, FsEntry { kind: NodeKind::File, exec, content: vec![], blob: e.blob, content_hash: Some(e.hash.clone()) });

                    }

                    Some(e) => {

                        out.insert(rel, FsEntry { kind: NodeKind::File, exec, content: fs::read(path)?, blob: None, content_hash: Some(e.hash.clone()) });

                    }

                    None => {

                        out.insert(rel, FsEntry::new(NodeKind::File, exec, fs::read(path)?));

                    }

                }

/// One manifest entry: the file's stat, its content hash, and the stored

/// blob for an opaque file.

#[derive(Clone, Debug)]

pub(crate) struct ManifestEntry {

    pub size: u64,

    pub mtime_ns: u128,

    pub hash: String,

    pub blob: Option<ObjectRef>,

}

#[derive(Clone, Debug, Default)]

pub(crate) struct Manifest {

    /// When the manifest was written, for the racy-stat guard.

    pub written_ns: u128,

    pub entries: BTreeMap<String, ManifestEntry>,

}

pub(crate) fn mtime_ns(m: &fs::Metadata) -> u128 {

    m.modified().ok().and_then(|t| t.duration_since(UNIX_EPOCH).ok()).map(|d| d.as_nanos()).unwrap_or(0)

}

/// One manifest line per file: size, mtime in nanoseconds, hash, blob ref

/// or `-`, path.

fn manifest_line(path: &str, size: u64, mtime_ns: u128, hash: &str, blob: Option<ObjectRef>) -> String {

    format!("{size}\t{mtime_ns}\t{hash}\t{}\t{path}\n", blob.map(|b| b.to_hex()).unwrap_or_else(|| "-".into()))

        let entries = self.walk_working_copy()?;

        self.write_manifest_entries(conflicted, uncommitted, &entries, &HashMap::new())

    }

    /// Write the manifest from entries already walked; `blobs` names the

    /// stored blob of each opaque path so the next walk can skip reading it.

    pub(crate) fn write_manifest_entries(&self, conflicted: bool, uncommitted: bool, entries: &BTreeMap<String, FsEntry>, blobs: &HashMap<String, ObjectRef>) -> Result<()> {

        let written = std::time::SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_nanos()).unwrap_or(0);

        let mut text = format!("# conflicted={}\n# uncommitted={}\n# written={written}\n", conflicted as u8, uncommitted as u8);

        for (path, e) in entries {

            let full = self.root.join(path);

                Ok(m) => (m.len(), mtime_ns(&m)),

            let hash = match &e.content_hash {

                Some(h) => h.clone(),

                None => blake3::hash(&e.content).to_hex().to_string(),

            };

            let blob = blobs.get(path).copied().or(e.blob);

            text.push_str(&manifest_line(path, size, mtime_ns, &hash, blob));

    /// Change only the header flags of the current manifest (after a commit

    /// the files are as the snapshot left them).

    pub(crate) fn rewrite_manifest_flags(&self, conflicted: bool, uncommitted: bool) -> Result<()> {

        let p = self.manifest_path();

        let text = match fs::read_to_string(&p) {

            Ok(t) => t,

            Err(_) => return self.write_manifest(conflicted, uncommitted),

        };

        let mut out = String::with_capacity(text.len());

        for line in text.lines() {

            if line.starts_with("# conflicted=") {

                out.push_str(&format!("# conflicted={}\n", conflicted as u8));

            } else if line.starts_with("# uncommitted=") {

                out.push_str(&format!("# uncommitted={}\n", uncommitted as u8));

            } else {

                out.push_str(line);

                out.push('\n');

            }

        }

        write_atomic(&p, out.as_bytes())

    }

    pub(crate) fn read_manifest(&self) -> Result<Option<(bool, bool, Manifest)>> {

        let mut out = Manifest::default();

            if let Some(v) = line.strip_prefix("# written=") {

                out.written_ns = v.trim().parse().unwrap_or(u128::MAX);

                continue;

            }

            let f: Vec<&str> = line.splitn(5, '\t').collect();

            if f.len() == 5 {

                out.entries.insert(

                    f[4].to_string(),

                    ManifestEntry { size: f[0].parse().unwrap_or(0), mtime_ns: f[1].parse().unwrap_or(0), hash: f[2].to_string(), blob: ObjectRef::from_hex(f[3]) },

                );

            let Some(me) = manifest.entries.get(&rel) else { return Ok(Some(true)) };

            let now_mtime = mtime_ns(&m);

                if blake3::hash(target.to_string_lossy().as_bytes()).to_hex().as_str() != me.hash {

            if m.len() != me.size {

            if now_mtime != me.mtime_ns && blake3::hash(&fs::read(entry.path())?).to_hex().as_str() != me.hash {

        Ok(Some(seen != manifest.entries.len()))

    /// The stored blob of every opaque path, for the manifest's stat cache.

    pub blobs: HashMap<String, ObjectRef>,

        Ok(BuiltChange { tree_ops: b.tree_ops, edits: b.edits, contributors: b.contributors.into_iter().collect(), resolves: b.resolves, statuses, blobs: b.blobs })

        // The last manifest lets unchanged opaque files go unread.

        let manifest = self.read_manifest()?.map(|(_, _, m)| m);

        let fs_entries = self.walk_working_copy_with(manifest.as_ref())?;

        let built = self.build_from_entries(&base, &base_snapshot, reuse, &fs_entries)?;

        self.write_manifest_entries(base_snapshot.is_conflicted(), !wc.tree_ops.is_empty() || !wc.edits.is_empty(), &fs_entries, &built.blobs)?;

        self.rewrite_manifest_flags(snap.base_snapshot.is_conflicted() && !snap.resolves, false)?;

    blobs: HashMap<String, ObjectRef>,

        ChangeBuilder { base, base_snapshot, tree_ops: vec![], edits: vec![], statuses: vec![], dir_nodes, reuse, contributors: BTreeSet::new(), resolves: false, attrs: crate::attributes::Attributes::default(), blobs: HashMap::new() }

    /// The blob for an opaque entry: the cached one, else stored now.

    fn blob_of(&mut self, repo: &Repo, path: &str, e: &FsEntry, nocompress: bool) -> Result<ObjectRef> {

        let b = match e.blob {

            Some(b) => b,

            None => repo.store_blob_for(&e.content, nocompress)?,

        };

        self.blobs.insert(path.to_string(), b);

        Ok(b)

    }

        if e.blob.is_some() {

            return true;

        }

            let blob = self.blob_of(repo, path, e, nocompress)?;

                    let blob = self.blob_of(repo, path, e, nocompress)?;

                let new_ref = e.blob.unwrap_or_else(|| Repo::blob_ref(&e.content));

                if e.kind == NodeKind::File && wants_opaque {

                    // Unchanged or replaced, the file stays opaque: remember its blob.

                    self.blobs.insert(path.to_string(), new_ref);

                }

                        let blob = self.blob_of(repo, path, e, nocompress)?;

                (None, Some(b)) if e.blob.unwrap_or_else(|| Repo::blob_ref(&e.content)) == b => 100,

/// An opaque file whose size and mtime match the manifest is not read on

/// the next snapshot: its blob comes from the manifest's stat cache.

#[cfg(unix)]

#[test]

fn stat_cache_skips_reading_unchanged_opaque_files() {

    use std::os::unix::fs::PermissionsExt;

    hermetic();

    let dir = tempfile::tempdir().unwrap();

    let root = dir.path();

    let repo = Repo::init(root).unwrap().with_home(root.join("home"));

    let mut big = vec![0u8; 300 * 1024];

    for (i, b) in big.iter_mut().enumerate() {

        *b = (i as u32).wrapping_mul(2654435761).to_le_bytes()[1];

    }

    big[0] = 0;

    write(root, "big.bin", &big);

    write(root, "a.txt", b"text\n");

    let h1 = repo.commit("base", &[]).unwrap();

    let (_, _, m) = repo.read_manifest().unwrap().unwrap();

    assert!(m.entries["big.bin"].blob.is_some(), "opaque files record their blob");

    assert!(m.entries["a.txt"].blob.is_none());

    let blob = m.entries["big.bin"].blob.unwrap();

    assert!(repo.store().has(&blob));

    // Files modified within two seconds of the manifest are racy and still

    // read; age the file so the cache applies, then snapshot to record it.

    let old = std::time::SystemTime::now() - std::time::Duration::from_secs(30);

    fs::File::options().write(true).open(root.join("big.bin")).unwrap().set_modified(old).unwrap();

    assert!(!repo.snapshot("status").unwrap().changed);

    // Now the file cannot be read at all; the snapshot succeeds without it.

    fs::set_permissions(root.join("big.bin"), fs::Permissions::from_mode(0o000)).unwrap();

    let snap = repo.snapshot("status").unwrap();

    assert!(!snap.changed && snap.statuses.is_empty(), "{:?}", snap.statuses);

    fs::set_permissions(root.join("big.bin"), fs::Permissions::from_mode(0o644)).unwrap();

    // A real change (new mtime, new content) is seen and committed correctly.

    let mut big2 = big.clone();

    big2[10] ^= 0xff;

    write(root, "big.bin", &big2);

    let snap = repo.snapshot("status").unwrap();

    assert_eq!(snap.statuses.iter().map(|s| (s.path.as_str(), s.status)).collect::<Vec<_>>(), vec![("big.bin", ChangeStatus::Modified)]);

    let h2 = repo.commit("edit", &[]).unwrap();

    let files = repo.load_state(&[h2]).unwrap().materialize().files;

    assert_eq!(files["big.bin"].content, FileContent::Opaque { blobs: vec![Repo::blob_ref(&big2)] });

    // Checkout writes a manifest with blobs too, so the next status is cached.

    repo.checkout(&[h1], false, "checkout").unwrap();

    let (_, _, m) = repo.read_manifest().unwrap().unwrap();

    assert_eq!(m.entries["big.bin"].blob, Some(Repo::blob_ref(&big)));

    assert!(!repo.snapshot("status").unwrap().changed);

}

- [x] Performance follow-up: `oxy status` re-hashes a clean 1 GiB working copy (2.4 s). Record size and mtime in the manifest and skip hashing files whose stat is unchanged (spec allows a stat cache). (Done: manifest records blob refs for opaque files; unchanged files are not read; two-second racy window; status on a clean 1 GiB copy 2.4 s → 4 ms; spec 0.6s.)

- 2026-09-27 09:10 iteration 16: manifest stat cache (status 2.4 s → 4 ms on 1 GiB). 112 tests.

| **Status** | Draft 0.6s |

The reference implementation's cache is the workspace **manifest** written after every snapshot, commit, and checkout: per file its size, mtime, content hash, and, for an opaque file, the ObjectRef of its stored blob. On the next snapshot a file whose size and mtime match is not read: an opaque file contributes its recorded blob, a text file keeps its recorded hash. A file whose mtime lies within two seconds of the manifest's own write time is never trusted (the racy-stat window), so a modification that preserves size and lands in the same timestamp tick is still seen. An implementation MAY use a file-system monitor instead of, or in addition to, the manifest.

*Changelog.* Draft 0.6s (2026-09-27): the manifest as a stat cache with a racy-stat window (§12.4).

Draft 0.6r (2026-09-27): batched object writes (§13.4).