crates/oxy-core/src/repo.rs at 5b9c6ad45f6e · andymccall/oxygen

# 5b9c6ad45f6e oxygen / crates / oxy-core / src / repo.rs
109.1 KiB · Rust · last changed Import the Oxygen specification and the first Rust implementation (root change) 1 month ago source blame history raw
//! A repository on disk: the `.oxy` directory, one workspace, the operation
//! log, and the working-copy change (spec §12, §13.1).
//!
//! Not yet implemented from the spec: trust policy (every remote is
//! "unverified", so unsigned pushes are accepted), packs, checkpoints,
//! multiple workspaces, and network transports (only local paths). Changes are signed individually when `core.sign` is
//! `change`; the default `seal` leaves them unsigned until push exists.

use crate::attest::{Attest, AttestBody};
use crate::diff::{ranges, split_lines, text_edits};
use crate::protocol::{open_remote, Bundle, RefResult, RefUpdate, RemoteRef, SignedAttest};
use crate::hash::{hash_object, ChangeHash, KeyId, ObjectRef, ObjectType};
use crate::identity::{self, Domain, Identity, SecretKey, Signature};
use crate::ids::{ChangeId, NodeId, WorkspaceId};
use crate::objects::{Blob, Change, ChangeKind, Edit, Hlc, Mode, NodeKind, OpRef, StateObject, TreeOp};
use crate::oplog::{Format1Op, Op, View, SNAPSHOT_SUFFIX};
use crate::state::{FileContent, Snapshot, State};
use crate::store::{Store, StoreError};
use crate::tree::OpKey;
use rand::RngCore;
use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::fs;
use std::io::Write;
use std::path::{Path, PathBuf};

pub const OXY_DIR: &str = ".oxy";
pub const FORMAT_LINE: &str = "oxy repository format 2\n";
const FORMAT1_LINE: &str = "oxy repository format 1\n";
const BINARY_SNIFF: usize = 8 * 1024;

#[derive(Debug, thiserror::Error)]
pub enum RepoError {
    #[error("io: {0}")]
    Io(#[from] std::io::Error),
    #[error(transparent)]
    Store(#[from] StoreError),
    #[error(transparent)]
    Object(#[from] crate::objects::ObjectError),
    #[error(transparent)]
    State(#[from] crate::state::StateError),
    #[error("{0}")]
    Msg(String),
}

pub type Result<T> = std::result::Result<T, RepoError>;

fn fail<T>(s: impl Into<String>) -> Result<T> {
    Err(RepoError::Msg(s.into()))
}

/// Repository-local settings (`.oxy/config`, `key = value` lines).
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Config {
    pub author_name: String,
    pub author_email: String,
    /// The KeyId of the author's identity, once `create_identity` has run.
    pub author_key: Option<KeyId>,
    /// `core.sign`: sign every change at commit (`true`) or leave signing to
    /// push-time seals (`false`, the spec default).
    pub sign_changes: bool,
    pub bookmark: String,
    /// `remote.<name>.url`.
    pub remotes: BTreeMap<String, String>,
}

impl Config {
    fn default_for_user() -> Config {
        let user = std::env::var("USER").unwrap_or_else(|_| "unknown".into());
        Config {
            author_name: std::env::var("OXY_AUTHOR_NAME").unwrap_or_else(|_| user.clone()),
            author_email: std::env::var("OXY_AUTHOR_EMAIL").unwrap_or_else(|_| format!("{user}@localhost")),
            author_key: None,
            sign_changes: false,
            bookmark: "main".into(),
            remotes: BTreeMap::new(),
        }
    }

    /// Set a key as `oxy config` does; returns false for unknown keys.
    pub fn set(&mut self, key: &str, value: &str) -> Result<()> {
        match key {
            "author.name" => self.author_name = value.into(),
            "author.email" => self.author_email = value.into(),
            "author.key" => {
                self.author_key = if value.is_empty() {
                    None
                } else {
                    Some(KeyId::from_hex(value).ok_or_else(|| RepoError::Msg("author.key must be a 64-character hex KeyId".into()))?)
                }
            }
            "core.sign" => {
                self.sign_changes = match value {
                    "change" => true,
                    "seal" => false,
                    _ => return fail("core.sign must be \"change\" or \"seal\""),
                }
            }
            "workspace.bookmark" => self.bookmark = value.into(),
            k if k.starts_with("remote.") && k.ends_with(".url") => {
                let name = &k["remote.".len()..k.len() - ".url".len()];
                if name.is_empty() || name.contains('/') {
                    return fail(format!("invalid remote name in {key:?}"));
                }
                if value.is_empty() {
                    self.remotes.remove(name);
                } else {
                    self.remotes.insert(name.to_string(), value.into());
                }
            }
            _ => return fail(format!("unknown configuration key {key:?}")),
        }
        Ok(())
    }

    fn load(path: &Path) -> Result<Config> {
        let mut c = Config::default_for_user();
        for line in fs::read_to_string(path)?.lines() {
            let line = line.trim();
            if line.is_empty() || line.starts_with('#') {
                continue;
            }
            let Some((k, v)) = line.split_once('=') else { continue };
            let v = v.trim().trim_matches('"').to_string();
            let _ = c.set(k.trim(), &v);
        }
        Ok(c)
    }

    fn save(&self, path: &Path) -> Result<()> {
        let mut text = format!(
            "author.name = \"{}\"\nauthor.email = \"{}\"\nauthor.key = \"{}\"\ncore.sign = \"{}\"\nworkspace.bookmark = \"{}\"\n",
            self.author_name,
            self.author_email,
            self.author_key.map(|k| k.to_hex()).unwrap_or_default(),
            if self.sign_changes { "change" } else { "seal" },
            self.bookmark
        );
        for (name, url) in &self.remotes {
            text.push_str(&format!("remote.{name}.url = \"{url}\"\n"));
        }
        write_atomic(path, text.as_bytes())
    }
}

fn write_atomic(path: &Path, data: &[u8]) -> Result<()> {
    let tmp = path.with_extension("tmp");
    {
        let mut f = fs::File::create(&tmp)?;
        f.write_all(data)?;
        f.sync_all()?;
    }
    fs::rename(&tmp, path)?;
    Ok(())
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ChangeStatus {
    Added,
    Modified,
    Removed,
    ModeChanged,
    /// The file is conflicted in the base state and still contains conflict markers.
    ConflictEdited,
    /// The file was conflicted in the base state and the working copy resolves it.
    Resolved,
}

/// Lines that mark a conflict region in a materialized file (spec §9.5).
pub fn has_conflict_markers(content: &[u8]) -> bool {
    split_lines(content).iter().any(|l| {
        l.starts_with(b"<<<<<<< oxy conflict") || l.starts_with(b"======= oxy conflict") || l.starts_with(b">>>>>>> oxy conflict")
    })
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct PathStatus {
    pub path: String,
    pub status: ChangeStatus,
}

/// Result of snapshotting the working copy.
pub struct SnapshotResult {
    pub wc_hash: ChangeHash,
    pub wc: Change,
    /// The base state (closure of the working-copy change's dependencies).
    pub base: State,
    pub base_snapshot: Snapshot,
    pub statuses: Vec<PathStatus>,
    /// Whether the snapshot rewrote the working-copy change.
    pub changed: bool,
    /// Whether the working copy resolves conflicts of its base (spec §9.6).
    pub resolves: bool,
}

pub struct LogEntry {
    pub hash: ChangeHash,
    pub change: Change,
    pub is_working_copy: bool,
    pub is_head: bool,
}

struct FsEntry {
    kind: NodeKind,
    exec: bool,
    content: Vec<u8>,
}

pub struct Repo {
    root: PathBuf,
    oxy: PathBuf,
    store: Store,
    workspace: WorkspaceId,
    keys_dir: PathBuf,
    pub config: Config,
}

/// Where secret keys live: `$OXY_HOME/keys`, else `$XDG_CONFIG_HOME/oxy/keys`,
/// else `~/.config/oxy/keys`.
pub fn default_keys_dir() -> PathBuf {
    if let Ok(h) = std::env::var("OXY_HOME") {
        return PathBuf::from(h).join("keys");
    }
    if let Ok(x) = std::env::var("XDG_CONFIG_HOME") {
        return PathBuf::from(x).join("oxy").join("keys");
    }
    let home = std::env::var("HOME").unwrap_or_else(|_| ".".into());
    PathBuf::from(home).join(".config").join("oxy").join("keys")
}

/// Outcome of verifying the signatures on a change (spec §14.3, §14.4).
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum SignatureStatus {
    Unsigned,
    Valid { key: KeyId, name: String, email: String, sealed: bool },
    Invalid(String),
}

pub fn is_binary(content: &[u8]) -> bool {
    content[..content.len().min(BINARY_SNIFF)].contains(&0)
}

impl Repo {
    // ------------------------------------------------------------ lifecycle

    pub fn init(root: &Path) -> Result<Repo> {
        let mut id = [0u8; 16];
        rand::rngs::OsRng.fill_bytes(&mut id);
        Self::init_with_id(root, id)
    }

    /// Initialize a repository with a given repository ID (clones share the
    /// ID of their origin, spec §14.4).
    pub fn init_with_id(root: &Path, id: [u8; 16]) -> Result<Repo> {
        fs::create_dir_all(root)?;
        let root = root.canonicalize().unwrap_or_else(|_| root.to_path_buf());
        let oxy = root.join(OXY_DIR);
        if oxy.exists() {
            return fail(format!("{} is already an oxy repository", root.display()));
        }
        fs::create_dir_all(oxy.join("ops"))?;
        write_atomic(&oxy.join("format"), FORMAT_LINE.as_bytes())?;
        write_atomic(&oxy.join("id"), hex::encode(id).as_bytes())?;
        let config = Config::default_for_user();
        config.save(&oxy.join("config"))?;
        let workspace = WorkspaceId::random();
        write_atomic(&oxy.join("workspace"), workspace.to_hex().as_bytes())?;
        let store = Store::open(oxy.join("objects"))?;
        let repo = Repo { root, oxy, store, workspace, keys_dir: default_keys_dir(), config };

        let wc = repo.new_working_copy(vec![], "");
        let wc_hash = repo.store.put_change(&wc)?;
        let mut view = View::default();
        view.bookmarks.insert(repo.config.bookmark.clone(), repo.store.put_state(&StateObject::new(vec![]))?);
        view.workspaces.insert(workspace, wc_hash);
        repo.record_op(&[], "oxy init", view)?;
        Ok(repo)
    }

    /// Open the repository containing `start` (searching upwards).
    pub fn open(start: &Path) -> Result<Repo> {
        let start = start.canonicalize()?;
        let mut dir: Option<&Path> = Some(&start);
        while let Some(d) = dir {
            let oxy = d.join(OXY_DIR);
            if oxy.is_dir() {
                let format = fs::read_to_string(oxy.join("format"))?;
                let config = Config::load(&oxy.join("config"))?;
                let workspace = WorkspaceId::from_hex(fs::read_to_string(oxy.join("workspace"))?.trim())
                    .ok_or_else(|| RepoError::Msg("corrupt .oxy/workspace".into()))?;
                let store = Store::open(oxy.join("objects"))?;
                let repo = Repo { root: d.to_path_buf(), oxy, store, workspace, keys_dir: default_keys_dir(), config };
                if format == FORMAT1_LINE {
                    repo.migrate_format1()?;
                } else if format != FORMAT_LINE {
                    return fail(format!("unsupported repository format: {}", format.trim()));
                }
                return Ok(repo);
            }
            dir = d.parent();
        }
        fail(format!("no oxy repository found at or above {}", start.display()))
    }

    /// Rewrite a format-1 operation log, whose bookmarks were head lists,
    /// into format 2, where each bookmark names a `state` object.
    fn migrate_format1(&self) -> Result<()> {
        let hex = fs::read_to_string(self.oxy.join("ops").join("head"))?;
        let head = ObjectRef::from_hex(hex.trim()).ok_or_else(|| RepoError::Msg("corrupt .oxy/ops/head".into()))?;
        // Collect the chain root-first.
        let mut chain: Vec<Format1Op> = Vec::new();
        let mut cur = Some(head);
        while let Some(r) = cur {
            let op = Op::decode_format1(&self.store.get_typed(&r, ObjectType::Op)?)?;
            cur = op.parents.first().copied();
            chain.push(op);
        }
        chain.reverse();
        let mut new_parent: Option<ObjectRef> = None;
        for old in chain {
            let mut view = View::default();
            for (name, heads) in &old.view.bookmarks {
                view.bookmarks.insert(name.clone(), self.store.put_state(&StateObject::new(heads.clone()))?);
            }
            view.workspaces = old.view.workspaces.clone();
            let op = Op { parents: new_parent.into_iter().collect(), hlc: old.hlc, command: old.command, view };
            new_parent = Some(self.store.put(ObjectType::Op, &op.encode())?);
        }
        write_atomic(&self.oxy.join("ops").join("head"), new_parent.unwrap().to_hex().as_bytes())?;
        write_atomic(&self.oxy.join("format"), FORMAT_LINE.as_bytes())?;
        Ok(())
    }

    /// The repository ID (spec §14.4). Repositories made before IDs existed get one on first use.
    pub fn id(&self) -> Result<[u8; 16]> {
        let path = self.oxy.join("id");
        match fs::read_to_string(&path) {
            Ok(h) => hex::decode(h.trim()).ok().and_then(|v| v.try_into().ok()).ok_or_else(|| RepoError::Msg("corrupt .oxy/id".into())),
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
                let mut id = [0u8; 16];
                rand::rngs::OsRng.fill_bytes(&mut id);
                write_atomic(&path, hex::encode(id).as_bytes())?;
                Ok(id)
            }
            Err(e) => Err(e.into()),
        }
    }

    pub fn root(&self) -> &Path {
        &self.root
    }
    pub fn store(&self) -> &Store {
        &self.store
    }
    pub fn workspace(&self) -> WorkspaceId {
        self.workspace
    }

    /// Use a different secret key directory (tests, or `--keys-dir`).
    pub fn with_keys_dir(mut self, dir: impl Into<PathBuf>) -> Repo {
        self.keys_dir = dir.into();
        self
    }

    pub fn save_config(&self) -> Result<()> {
        self.config.save(&self.oxy.join("config"))
    }

    fn author(&self) -> KeyId {
        self.config.author_key.unwrap_or(ObjectRef::ZERO)
    }

    // ------------------------------------------------------------ identity

    /// Generate a composite key pair, store its identity object, keep the
    /// secret in the key directory, and make it this repository's author.
    pub fn create_identity(&mut self, name: &str, email: &str) -> Result<(KeyId, Identity)> {
        let sk = SecretKey::generate();
        let id = sk.identity(name, email, Hlc::now().wall_ms);
        let key = self.store.put_identity(&id)?;
        fs::create_dir_all(&self.keys_dir)?;
        let path = self.keys_dir.join(format!("{}.secret", key.to_hex()));
        write_atomic(&path, &sk.encode(&key))?;
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            fs::set_permissions(&path, fs::Permissions::from_mode(0o600))?;
        }
        self.config.author_name = name.into();
        self.config.author_email = email.into();
        self.config.author_key = Some(key);
        self.save_config()?;
        Ok((key, id))
    }

    /// The secret key for `author.key`, if configured and present on disk.
    pub fn secret_key(&self) -> Result<Option<(KeyId, SecretKey)>> {
        let Some(key) = self.config.author_key else { return Ok(None) };
        let path = self.keys_dir.join(format!("{}.secret", key.to_hex()));
        match fs::read(&path) {
            Ok(b) => {
                let (k, sk) = SecretKey::decode(&b)?;
                if k != key {
                    return fail(format!("{} holds a different key than its name", path.display()));
                }
                Ok(Some((k, sk)))
            }
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
            Err(e) => Err(e.into()),
        }
    }

    pub fn identity(&self, key: &KeyId) -> Result<Identity> {
        Ok(self.store.get_identity(key)?)
    }

    /// Sign a stored change with the configured secret key.
    pub fn sign_change(&self, hash: &ChangeHash) -> Result<Signature> {
        let Some((key, sk)) = self.secret_key()? else {
            return fail("no secret key: run `oxy identity create` first");
        };
        let sig = sk.sign(Domain::Change, &key, hash);
        self.store.put_signature(hash, &sig)?;
        Ok(sig)
    }

    /// Check the signatures on a change against the author-or-delegate rule.
    pub fn verify_change(&self, hash: &ChangeHash) -> Result<SignatureStatus> {
        let change = self.store.get_change(hash)?;
        let sigs = self.store.signatures(hash)?;
        if sigs.is_empty() {
            return Ok(SignatureStatus::Unsigned);
        }
        let mut last_err = String::new();
        for sig in &sigs {
            match self.check_signer(&change, sig, Domain::Change, hash) {
                Ok(id) => return Ok(SignatureStatus::Valid { key: sig.key, name: id.name, email: id.email, sealed: false }),
                Err(e) => last_err = e,
            }
        }
        Ok(SignatureStatus::Invalid(last_err))
    }

    /// Verify `sig` over `target` and check the author-or-delegate rule for `change`.
    fn check_signer(&self, change: &Change, sig: &Signature, domain: Domain, target: &ObjectRef) -> std::result::Result<Identity, String> {
        let id = self.store.get_identity(&sig.key).map_err(|_| format!("unknown key {}", sig.key.short(12)))?;
        let authorised =
            sig.key == change.author || self.store.get_identity(&change.author).map(|a| a.delegates.contains(&sig.key)).unwrap_or(false);
        if !authorised {
            return Err(format!("key {} is neither the author nor a delegate", sig.key.short(12)));
        }
        identity::verify(&id, sig, domain, target).map_err(|e| e.to_string())?;
        Ok(id)
    }

    /// Like `verify_change`, but a change with no valid individual signature
    /// is also authenticated by a valid seal covering it (spec §14.4).
    pub fn authenticate_change(&self, hash: &ChangeHash) -> Result<SignatureStatus> {
        let direct = self.verify_change(hash)?;
        if matches!(direct, SignatureStatus::Valid { .. }) {
            return Ok(direct);
        }
        let change = self.store.get_change(hash)?;
        let mut last_err = match &direct {
            SignatureStatus::Invalid(e) => e.clone(),
            _ => String::new(),
        };
        for seal_ref in self.store.seals_for(hash)? {
            let attest = self.store.get_attest(&seal_ref)?;
            let AttestBody::Seal { hashes } = &attest.body else { continue };
            if !hashes.contains(hash) {
                continue;
            }
            for sig in self.store.signatures(&seal_ref)? {
                match self.check_signer(&change, &sig, Domain::Attest, &seal_ref) {
                    Ok(id) => return Ok(SignatureStatus::Valid { key: sig.key, name: id.name, email: id.email, sealed: true }),
                    Err(e) => last_err = e,
                }
            }
        }
        if last_err.is_empty() { Ok(SignatureStatus::Unsigned) } else { Ok(SignatureStatus::Invalid(last_err)) }
    }

    /// Store and sign an attestation with the configured key.
    fn sign_attest(&self, attest: &Attest) -> Result<SignedAttest> {
        let Some((key, sk)) = self.secret_key()? else {
            return fail("no secret key: run `oxy identity create` first");
        };
        let r = self.store.put_attest(attest)?;
        let sig = sk.sign(Domain::Attest, &key, &r);
        self.store.put_signature(&r, &sig)?;
        if let AttestBody::Seal { hashes } = &attest.body {
            for h in hashes {
                self.store.index_seal(h, &r)?;
            }
        }
        Ok(SignedAttest { attest: attest.clone(), sigs: vec![sig] })
    }

    // ------------------------------------------------------------ serving (spec §16)

    fn ref_attest_path(&self, bookmark: &str) -> PathBuf {
        self.oxy.join("attest").join(bookmark)
    }

    /// The latest reference attestation stored for a bookmark.
    pub fn latest_ref_attest(&self, bookmark: &str) -> Result<Option<(ObjectRef, SignedAttest)>> {
        match fs::read_to_string(self.ref_attest_path(bookmark)) {
            Ok(h) => {
                let r = ObjectRef::from_hex(h.trim()).ok_or_else(|| RepoError::Msg("corrupt attestation pointer".into()))?;
                Ok(Some((r, SignedAttest { attest: self.store.get_attest(&r)?, sigs: self.store.signatures(&r)? })))
            }
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
            Err(e) => Err(e.into()),
        }
    }

    fn set_ref_attest(&self, bookmark: &str, r: &ObjectRef) -> Result<()> {
        fs::create_dir_all(self.oxy.join("attest"))?;
        write_atomic(&self.ref_attest_path(bookmark), r.to_hex().as_bytes())
    }

    pub fn remote_refs(&self) -> Result<Vec<RemoteRef>> {
        let view = self.view()?;
        let mut out = Vec::new();
        for (name, state) in &view.bookmarks {
            out.push(RemoteRef {
                name: name.clone(),
                state: *state,
                heads: self.store.get_state(state)?.heads,
                attestation: self.latest_ref_attest(name)?.map(|(_, a)| a),
            });
        }
        Ok(out)
    }

    /// Every change reachable from `heads` that is in the store.
    fn closure_in_store(&self, heads: &[ChangeHash]) -> Result<BTreeSet<ChangeHash>> {
        let mut seen = BTreeSet::new();
        let mut stack: Vec<ChangeHash> = heads.to_vec();
        while let Some(h) = stack.pop() {
            if seen.contains(&h) || !self.store.has(&h) {
                continue;
            }
            seen.insert(h);
            stack.extend(self.store.get_change(&h)?.deps);
        }
        Ok(seen)
    }

    /// `closure(want) \ closure(have)`, dependencies first (spec §16.2).
    pub fn negotiate(&self, have: &[ChangeHash], want: &[ChangeHash]) -> Result<Vec<ChangeHash>> {
        let have = self.closure_in_store(have)?;
        let mut out = Vec::new();
        let mut done: BTreeSet<ChangeHash> = have.clone();
        // Iterative post-order DFS.
        let mut stack: Vec<(ChangeHash, bool)> = want.iter().rev().map(|h| (*h, false)).collect();
        while let Some((h, expanded)) = stack.pop() {
            if done.contains(&h) {
                continue;
            }
            if !self.store.has(&h) {
                return fail(format!("change {} is not in this repository", h.short(12)));
            }
            if expanded {
                done.insert(h);
                out.push(h);
                continue;
            }
            stack.push((h, true));
            for d in self.store.get_change(&h)?.deps {
                if !done.contains(&d) {
                    stack.push((d, false));
                }
            }
        }
        Ok(out)
    }

    /// Bundle changes (in the given dependency order) with their signatures,
    /// seals, identities, blobs, chunks.
    pub fn bundle_for(&self, changes: &[ChangeHash]) -> Result<Bundle> {
        let mut bundle = Bundle::default();
        let mut objects: BTreeSet<ObjectRef> = BTreeSet::new();
        let mut seals: BTreeSet<ObjectRef> = BTreeSet::new();
        let add_object = |r: &ObjectRef, objects: &mut BTreeSet<ObjectRef>| {
            if !r.is_zero() && self.store.has(r) {
                objects.insert(*r);
            }
        };
        for h in changes {
            let c = self.store.get_change(h)?;
            let sigs = self.store.signatures(h)?;
            add_object(&c.author, &mut objects);
            for s in &sigs {
                add_object(&s.key, &mut objects);
            }
            for e in &c.edits {
                if let Edit::Replace { old, new, .. } = e {
                    for b in [old, new].into_iter().flatten() {
                        if self.store.has(b) {
                            objects.insert(*b);
                            if let Ok(blob) = Blob::decode(&self.store.get_typed(b, ObjectType::Blob)?) {
                                objects.extend(blob.chunks.iter().copied());
                            }
                        }
                    }
                }
            }
            for s in self.store.seals_for(h)? {
                seals.insert(s);
            }
            bundle.changes.push((c, sigs));
        }
        for r in seals {
            let attest = self.store.get_attest(&r)?;
            let sigs = self.store.signatures(&r)?;
            for s in &sigs {
                add_object(&s.key, &mut objects);
            }
            bundle.attests.push(SignedAttest { attest, sigs });
        }
        for r in objects {
            let (ty, body) = self.store.get(&r)?;
            bundle.objects.push((ty, body));
        }
        Ok(bundle)
    }

    /// Store a bundle's contents. With `strict`, every change must
    /// authenticate (signature or seal by its author or a delegate).
    pub fn import_bundle(&self, bundle: &Bundle, strict: bool) -> Result<Vec<ChangeHash>> {
        for (ty, body) in &bundle.objects {
            match ty {
                ObjectType::Chunk | ObjectType::Blob | ObjectType::Identity | ObjectType::State => {
                    self.store.put(*ty, body)?;
                }
                other => return fail(format!("bundle may not carry {} objects", other.name())),
            }
        }
        for sa in &bundle.attests {
            let r = self.store.put_attest(&sa.attest)?;
            for sig in &sa.sigs {
                self.store.put_signature(&r, sig)?;
            }
            if let AttestBody::Seal { hashes } = &sa.attest.body {
                for h in hashes {
                    self.store.index_seal(h, &r)?;
                }
            }
        }
        let incoming: BTreeSet<ChangeHash> = bundle.changes.iter().map(|(c, _)| c.hash()).collect();
        let mut imported = Vec::new();
        for (c, sigs) in &bundle.changes {
            let h = c.hash();
            for d in &c.deps {
                if !self.store.has(d) && !incoming.contains(d) {
                    return fail(format!("change {} depends on {}, which is neither stored nor in the bundle", h.short(12), d.short(12)));
                }
            }
            self.store.put_change(c)?;
            for sig in sigs {
                self.store.put_signature(&h, sig)?;
            }
            imported.push(h);
        }
        if strict {
            for h in &imported {
                if !matches!(self.authenticate_change(h)?, SignatureStatus::Valid { .. }) {
                    return fail(format!("change {} is not authenticated by its author", h.short(12)));
                }
            }
        }
        Ok(imported)
    }

    /// Verify a reference attestation against an update it claims to describe.
    fn check_ref_attest(&self, sa: &SignedAttest, name: &str, old_state: &ObjectRef, new_state: &ObjectRef, last_serial: Option<u64>) -> std::result::Result<u64, String> {
        let AttestBody::Ref { name: n, old_state: o, new_state: nw, serial } = &sa.attest.body else {
            return Err("attestation is not a ref attestation".into());
        };
        if n != name || o != old_state || nw != new_state {
            return Err("attestation does not describe this update".into());
        }
        if sa.attest.repo != self.id().map_err(|e| e.to_string())? {
            return Err("attestation is for a different repository".into());
        }
        if let Some(last) = last_serial {
            if *serial <= last {
                return Err(format!("attestation serial {serial} is not greater than the last seen {last}"));
            }
        }
        let r = sa.attest.hash();
        let sig = sa.sigs.first().ok_or("attestation carries no signature")?;
        let id = self.store.get_identity(&sig.key).map_err(|_| format!("unknown key {}", sig.key.short(12)))?;
        identity::verify(&id, sig, Domain::Attest, &r).map_err(|e| e.to_string())?;
        Ok(*serial)
    }

    /// Accept a push (spec §16.3). Without a trust policy every repository
    /// is unverified, so unsigned changes and unattested updates are accepted;
    /// attestations that are present must still be valid.
    pub fn receive_push(&self, bundle: Bundle, updates: Vec<RefUpdate>) -> Result<Vec<RefResult>> {
        self.import_bundle(&bundle, false)?;
        let (op_ref, op) = self.head_op()?;
        let mut view = op.view.clone();
        let mut results = Vec::new();
        let mut names = Vec::new();
        for u in updates {
            let outcome = self.apply_update(&mut view, &u);
            let (ok, reason) = match outcome {
                Ok(()) => (true, String::new()),
                Err(e) => (false, e),
            };
            if ok {
                names.push(u.name.clone());
            }
            results.push(RefResult { name: u.name, ok, reason });
        }
        if !names.is_empty() {
            self.record_op(&[op_ref], &format!("push received: {}", names.join(" ")), view)?;
        }
        Ok(results)
    }

    fn apply_update(&self, view: &mut View, u: &RefUpdate) -> std::result::Result<(), String> {
        let empty = self.store.put_state(&StateObject::new(vec![])).map_err(|e| e.to_string())?;
        let current = view.bookmarks.get(&u.name).copied().unwrap_or(empty);
        if current != u.old_state {
            return Err("stale: the remote bookmark has moved; pull first".into());
        }
        let new_state = self.store.get_state(&u.new_state).map_err(|_| "new state object is missing".to_string())?;
        for h in &new_state.heads {
            if !self.store.has(h) {
                return Err(format!("head {} is missing", h.short(12)));
            }
        }
        if !u.force {
            let old_heads = self.store.get_state(&current).map_err(|e| e.to_string())?.heads;
            let closure = self.closure_in_store(&new_state.heads).map_err(|e| e.to_string())?;
            if let Some(h) = old_heads.iter().find(|h| !closure.contains(h)) {
                return Err(format!("not a fast-forward: current head {} would be dropped (use --force)", h.short(12)));
            }
        }
        if let Some(sa) = &u.attestation {
            let last = self.latest_ref_attest(&u.name).map_err(|e| e.to_string())?.and_then(|(_, a)| match a.attest.body {
                AttestBody::Ref { serial, .. } => Some(serial),
                _ => None,
            });
            self.check_ref_attest(sa, &u.name, &u.old_state, &u.new_state, last)?;
            let r = self.store.put_attest(&sa.attest).map_err(|e| e.to_string())?;
            for sig in &sa.sigs {
                self.store.put_signature(&r, sig).map_err(|e| e.to_string())?;
            }
            self.set_ref_attest(&u.name, &r).map_err(|e| e.to_string())?;
        }
        view.bookmarks.insert(u.name.clone(), u.new_state);
        Ok(())
    }

    // ------------------------------------------------------------ client side

    fn remote_url(&self, name: &str) -> Result<String> {
        self.config.remotes.get(name).cloned().ok_or_else(|| RepoError::Msg(format!("no remote named {name:?}; add one with `oxy remote add`")))
    }

    fn serial_path(&self, remote: &str, bookmark: &str) -> PathBuf {
        self.oxy.join("remotes").join(remote).join(format!("{bookmark}.serial"))
    }

    fn last_seen_serial(&self, remote: &str, bookmark: &str) -> Option<u64> {
        fs::read_to_string(self.serial_path(remote, bookmark)).ok().and_then(|s| s.trim().parse().ok())
    }

    fn record_serial(&self, remote: &str, bookmark: &str, serial: u64) -> Result<()> {
        let p = self.serial_path(remote, bookmark);
        fs::create_dir_all(p.parent().unwrap())?;
        write_atomic(&p, serial.to_string().as_bytes())
    }

    /// Every head this repository knows: bookmarks, remote tracking, working copy.
    fn known_heads(&self, view: &View) -> Result<Vec<ChangeHash>> {
        let mut have: BTreeSet<ChangeHash> = BTreeSet::new();
        for st in view.bookmarks.values().chain(view.remotes.values().flat_map(|b| b.values())) {
            if let Ok(s) = self.store.get_state(st) {
                have.extend(s.heads);
            }
        }
        have.extend(view.workspaces.values().copied());
        Ok(have.into_iter().collect())
    }

    /// Fetch every bookmark of a remote into `remotes/<name>/bookmarks/*` (spec §10.2).
    pub fn fetch(&self, remote_name: &str) -> Result<Vec<(String, Vec<ChangeHash>, usize)>> {
        let remote = open_remote(&self.remote_url(remote_name)?)?;
        if remote.repo_id()? != self.id()? {
            return fail(format!("remote {remote_name:?} is a different repository (repository IDs differ)"));
        }
        let (op_ref, op) = self.head_op()?;
        let mut view = op.view.clone();
        let have = self.known_heads(&view)?;
        let mut report = Vec::new();
        for r in remote.refs()? {
            let needed = remote.negotiate(&have, &r.heads)?;
            let bundle = remote.fetch(&needed)?;
            let imported = self.import_bundle(&bundle, false)?;
            for h in &r.heads {
                if !self.store.has(h) {
                    return fail(format!("remote did not send head {}", h.short(12)));
                }
            }
            let state = self.store.put_state(&StateObject::new(r.heads.clone()))?;
            if state != r.state {
                return fail(format!("remote state {} does not match its heads", r.state.short(12)));
            }
            if let Some(sa) = &r.attestation {
                let AttestBody::Ref { old_state, new_state, .. } = &sa.attest.body else {
                    return fail("remote sent a non-ref attestation for a bookmark");
                };
                let (old_state, new_state) = (*old_state, *new_state);
                let serial = self
                    .check_ref_attest(sa, &r.name, &old_state, &new_state, self.last_seen_serial(remote_name, &r.name))
                    .map_err(|e| RepoError::Msg(format!("attestation for {}/{}: {e}", remote_name, r.name)))?;
                if new_state != r.state {
                    return fail(format!("attestation for {}/{} does not cover its current state", remote_name, r.name));
                }
                let ar = self.store.put_attest(&sa.attest)?;
                for sig in &sa.sigs {
                    self.store.put_signature(&ar, sig)?;
                }
                self.record_serial(remote_name, &r.name, serial)?;
            }
            view.remotes.entry(remote_name.to_string()).or_default().insert(r.name.clone(), state);
            report.push((r.name, r.heads, imported.len()));
        }
        if view != op.view {
            self.record_op(&[op_ref], &format!("oxy fetch {remote_name}"), view)?;
        }
        Ok(report)
    }

    /// Fetch, then take the union of the local bookmark's state with the
    /// remote's: no merge change, conflicts become reified (spec §9.4).
    pub fn pull(&self, remote_name: &str) -> Result<PullReport> {
        self.fetch(remote_name)?;
        let (op_ref, op) = self.head_op()?;
        let bookmark = self.config.bookmark.clone();
        let local = self.heads_of(&op.view, &bookmark)?;
        let Some(remote_state) = op.view.remotes.get(remote_name).and_then(|b| b.get(&bookmark)).copied() else {
            return Ok(PullReport { heads: local, changed: false, checked_out: false });
        };
        let remote_heads = self.store.get_state(&remote_state)?.heads;
        let mut all = local.clone();
        all.extend(remote_heads);
        let st = self.load_state(&all)?;
        let mut heads = st.maximal(&all);
        heads.sort();
        let mut sorted_local = local.clone();
        sorted_local.sort();
        if heads == sorted_local {
            return Ok(PullReport { heads, changed: false, checked_out: false });
        }
        let mut view = op.view.clone();
        view.bookmarks.insert(bookmark.clone(), self.store.put_state(&StateObject::new(heads.clone()))?);
        self.record_op(&[op_ref], &format!("oxy pull {remote_name}"), view)?;
        // Follow along if the working copy was clean and on the old heads.
        let snap = self.snapshot("oxy pull")?;
        let clean = snap.wc.tree_ops.is_empty() && snap.wc.edits.is_empty();
        let mut base = snap.base.maximal(&snap.wc.deps);
        base.sort();
        let mut checked_out = false;
        if clean && base == sorted_local {
            self.checkout(&heads, false, "oxy pull (checkout)")?;
            checked_out = true;
        }
        Ok(PullReport { heads, changed: true, checked_out })
    }

    /// Push the current bookmark (spec §16.3), sealing this author's unsigned
    /// changes and attesting the reference when a key is available.
    pub fn push(&self, remote_name: &str, force: bool) -> Result<Vec<RefResult>> {
        let remote = open_remote(&self.remote_url(remote_name)?)?;
        if remote.repo_id()? != self.id()? {
            return fail(format!("remote {remote_name:?} is a different repository (repository IDs differ)"));
        }
        let (op_ref, op) = self.head_op()?;
        let bookmark = self.config.bookmark.clone();
        let local_heads = self.heads_of(&op.view, &bookmark)?;
        let refs = remote.refs()?;
        let empty = self.store.put_state(&StateObject::new(vec![]))?;
        let (remote_state, remote_heads, last_serial) = match refs.iter().find(|r| r.name == bookmark) {
            Some(r) => (
                r.state,
                r.heads.clone(),
                r.attestation.as_ref().and_then(|a| match a.attest.body {
                    AttestBody::Ref { serial, .. } => Some(serial),
                    _ => None,
                }),
            ),
            None => (empty, vec![], None),
        };
        let new_state = self.store.put_state(&StateObject::new(local_heads.clone()))?;
        if new_state == remote_state {
            return Ok(vec![RefResult { name: bookmark, ok: true, reason: "already up to date".into() }]);
        }
        for h in &remote_heads {
            if !self.store.has(h) {
                return fail(format!("the remote has change {} which you do not; pull first", h.short(12)));
            }
        }
        if !force {
            let closure = self.closure_in_store(&local_heads)?;
            if let Some(h) = remote_heads.iter().find(|h| !closure.contains(h)) {
                return fail(format!("not a fast-forward: remote head {} is not in your state; pull first or use --force", h.short(12)));
            }
        }
        let to_send = self.negotiate(&remote_heads, &local_heads)?;
        let mut bundle = self.bundle_for(&to_send)?;
        let key = self.secret_key()?.map(|(k, _)| k);
        if let Some(key) = key {
            // Seal this author's changes that carry no valid authenticator.
            let mut unsigned = Vec::new();
            for h in &to_send {
                let c = self.store.get_change(h)?;
                if c.author == key && !matches!(self.authenticate_change(h)?, SignatureStatus::Valid { .. }) {
                    unsigned.push(*h);
                }
            }
            for chunk in unsigned.chunks(crate::attest::MAX_SEAL_HASHES) {
                let sa = self.sign_attest(&Attest::seal(self.id()?, chunk.to_vec()))?;
                bundle.attests.push(sa);
            }
            bundle = self.bundle_for(&to_send)?;
        }
        bundle.objects.push((ObjectType::State, StateObject::new(local_heads.clone()).encode()));
        let attestation = match key {
            Some(_) => Some(self.sign_attest(&Attest {
                repo: self.id()?,
                hlc: Hlc::now(),
                body: AttestBody::Ref { name: bookmark.clone(), old_state: remote_state, new_state, serial: last_serial.unwrap_or(0) + 1 },
            })?),
            None => None,
        };
        let serial = attestation.as_ref().and_then(|a| match a.attest.body {
            AttestBody::Ref { serial, .. } => Some(serial),
            _ => None,
        });
        let results = remote.push(bundle, vec![RefUpdate { name: bookmark.clone(), old_state: remote_state, new_state, force, attestation }])?;
        if results.iter().any(|r| r.ok) {
            let mut view = op.view.clone();
            view.remotes.entry(remote_name.to_string()).or_default().insert(bookmark.clone(), new_state);
            self.record_op(&[op_ref], &format!("oxy push {remote_name}"), view)?;
            if let Some(s) = serial {
                self.record_serial(remote_name, &bookmark, s)?;
            }
        }
        Ok(results)
    }

    /// Clone a remote into `dest`: same repository ID, `origin` remote,
    /// bookmark set to the remote's, working copy checked out.
    pub fn clone(url: &str, dest: &Path) -> Result<Repo> {
        let remote = open_remote(url)?;
        let id = remote.repo_id()?;
        let mut repo = Repo::init_with_id(dest, id)?;
        repo.config.remotes.insert("origin".into(), url.to_string());
        repo.save_config()?;
        repo.fetch("origin")?;
        let (op_ref, op) = repo.head_op()?;
        let bookmark = repo.config.bookmark.clone();
        if let Some(state) = op.view.remotes.get("origin").and_then(|b| b.get(&bookmark)).copied() {
            let heads = repo.store.get_state(&state)?.heads;
            let mut view = op.view.clone();
            view.bookmarks.insert(bookmark, state);
            repo.record_op(&[op_ref], &format!("oxy clone {url}"), view)?;
            repo.checkout(&heads, false, "oxy clone (checkout)")?;
        }
        Ok(repo)
    }


    fn new_working_copy(&self, deps: Vec<ChangeHash>, message: &str) -> Change {
        let mut c = Change {
            change_id: ChangeId::random(),
            deps,
            author: self.author(),
            hlc: Hlc::now(),
            message: message.into(),
            tree_ops: vec![],
            edits: vec![],
            kind: ChangeKind::WorkingCopy,
        };
        c.normalize();
        c
    }

    // ------------------------------------------------------------ operation log

    pub fn head_op(&self) -> Result<(ObjectRef, Op)> {
        let hex = fs::read_to_string(self.oxy.join("ops").join("head"))?;
        let r = ObjectRef::from_hex(hex.trim()).ok_or_else(|| RepoError::Msg("corrupt .oxy/ops/head".into()))?;
        let op = Op::decode(&self.store.get_typed(&r, ObjectType::Op)?)?;
        Ok((r, op))
    }

    pub fn view(&self) -> Result<View> {
        Ok(self.head_op()?.1.view)
    }

    fn record_op(&self, parents: &[ObjectRef], command: &str, view: View) -> Result<ObjectRef> {
        let op = Op { parents: parents.to_vec(), hlc: Hlc::now(), command: command.into(), view };
        let r = self.store.put(ObjectType::Op, &op.encode())?;
        write_atomic(&self.oxy.join("ops").join("head"), r.to_hex().as_bytes())?;
        Ok(r)
    }

    pub fn op_log(&self) -> Result<Vec<(ObjectRef, Op)>> {
        let mut out = Vec::new();
        let (mut r, mut op) = self.head_op()?;
        loop {
            let next = op.parents.first().copied();
            out.push((r, op));
            match next {
                Some(p) => {
                    r = p;
                    op = Op::decode(&self.store.get_typed(&r, ObjectType::Op)?)?;
                }
                None => break,
            }
        }
        Ok(out)
    }

    /// Undo the last user command (spec §12.1). Operations that only recorded
    /// a working-copy snapshot are skipped, since the files are still on disk
    /// and the next snapshot recreates them.
    pub fn undo(&self) -> Result<Op> {
        let (_, mut op) = self.head_op()?;
        while op.is_snapshot() {
            let Some(parent) = op.parents.first() else { break };
            op = Op::decode(&self.store.get_typed(parent, ObjectType::Op)?)?;
        }
        let Some(parent) = op.parents.first() else {
            return fail("nothing to undo");
        };
        let parent_op = Op::decode(&self.store.get_typed(parent, ObjectType::Op)?)?;
        write_atomic(&self.oxy.join("ops").join("head"), parent.to_hex().as_bytes())?;
        Ok(parent_op)
    }

    /// The last operation that was not a snapshot.
    pub fn last_command(&self) -> Result<Op> {
        let (_, mut op) = self.head_op()?;
        while op.is_snapshot() {
            let Some(parent) = op.parents.first() else { break };
            op = Op::decode(&self.store.get_typed(parent, ObjectType::Op)?)?;
        }
        Ok(op)
    }

    // ------------------------------------------------------------ states

    /// Load the dependency closure of `heads` from the store.
    pub fn load_state(&self, heads: &[ChangeHash]) -> Result<State> {
        let mut state = State::new();
        let mut stack: Vec<ChangeHash> = heads.to_vec();
        let mut seen: BTreeSet<ChangeHash> = BTreeSet::new();
        while let Some(h) = stack.pop() {
            if !seen.insert(h) {
                continue;
            }
            let c = self.store.get_change(&h)?;
            stack.extend(c.deps.iter().copied());
            state.add_unchecked(c);
        }
        state.validate()?;
        Ok(state)
    }

    pub fn working_copy(&self) -> Result<(ChangeHash, Change)> {
        let view = self.view()?;
        let h = *view
            .workspaces
            .get(&self.workspace)
            .ok_or_else(|| RepoError::Msg("this workspace is not in the current view".into()))?;
        Ok((h, self.store.get_change(&h)?))
    }

    /// Heads of a bookmark's state (spec §10.1).
    pub fn heads_of(&self, view: &View, bookmark: &str) -> Result<Vec<ChangeHash>> {
        match view.bookmarks.get(bookmark) {
            Some(st) => Ok(self.store.get_state(st)?.heads),
            None => Ok(vec![]),
        }
    }

    pub fn bookmark_heads(&self) -> Result<Vec<ChangeHash>> {
        self.heads_of(&self.view()?, &self.config.bookmark)
    }

    // ------------------------------------------------------------ blobs

    fn blob_for(content: &[u8]) -> Blob {
        Blob {
            length: content.len() as u64,
            chunks: crate::chunk::chunks(content).into_iter().map(|c| hash_object(ObjectType::Chunk, c)).collect(),
        }
    }

    pub fn blob_ref(content: &[u8]) -> ObjectRef {
        Self::blob_for(content).hash()
    }

    pub fn store_blob(&self, content: &[u8]) -> Result<ObjectRef> {
        for c in crate::chunk::chunks(content) {
            self.store.put_chunk(c)?;
        }
        Ok(self.store.put(ObjectType::Blob, &Self::blob_for(content).encode())?)
    }

    pub fn read_blob(&self, r: &ObjectRef) -> Result<Vec<u8>> {
        let blob = Blob::decode(&self.store.get_typed(r, ObjectType::Blob)?)?;
        let mut out = Vec::with_capacity(blob.length as usize);
        for c in &blob.chunks {
            out.extend(self.store.get_typed(c, ObjectType::Chunk)?);
        }
        Ok(out)
    }

    // ------------------------------------------------------------ working copy

    fn walk_working_copy(&self) -> Result<BTreeMap<String, FsEntry>> {
        let mut wb = ignore::WalkBuilder::new(&self.root);
        wb.hidden(false)
            .git_ignore(false)
            .git_global(false)
            .git_exclude(false)
            .require_git(false)
            .follow_links(false)
            .add_custom_ignore_filename(".oxyignore");
        wb.filter_entry(|e| e.file_name() != OXY_DIR);
        let mut out = BTreeMap::new();
        for entry in wb.build() {
            let entry = entry.map_err(|e| RepoError::Msg(e.to_string()))?;
            let path = entry.path();
            if path == self.root {
                continue;
            }
            let rel = path.strip_prefix(&self.root).unwrap();
            let rel: String = rel.components().map(|c| c.as_os_str().to_string_lossy().to_string()).collect::<Vec<_>>().join("/");
            let Some(ft) = entry.file_type() else { continue };
            if ft.is_dir() {
                continue;
            }
            if ft.is_symlink() {
                let target = fs::read_link(path)?;
                out.insert(rel, FsEntry { kind: NodeKind::Symlink, exec: false, content: target.to_string_lossy().as_bytes().to_vec() });
            } else if ft.is_file() {
                let exec = is_executable(&entry.metadata().map_err(|e| RepoError::Msg(e.to_string()))?);
                out.insert(rel, FsEntry { kind: NodeKind::File, exec, content: fs::read(path)? });
            }
        }
        Ok(out)
    }

    /// Snapshot the working copy into the working-copy change (spec §12.3).
    pub fn snapshot(&self, command: &str) -> Result<SnapshotResult> {
        let (op_ref, op) = self.head_op()?;
        let (old_hash, old_wc) = self.working_copy()?;
        let base = self.load_state(&old_wc.deps)?;
        let base_snapshot = base.materialize();
        let fs_entries = self.walk_working_copy()?;

        // Reuse the NodeIds the previous working-copy version assigned to new
        // paths, so an unchanged working copy hashes identically (spec §12.3).
        let reuse = added_node_paths(&old_wc, &base_snapshot);
        let mut b = ChangeBuilder::new(&base, &base_snapshot, reuse);
        for (path, fs_entry) in &fs_entries {
            match base_snapshot.files.get(path) {
                None => b.add_path(self, path, fs_entry)?,
                Some(expected) => b.update_path(self, path, fs_entry, expected)?,
            }
        }
        for (path, expected) in &base_snapshot.files {
            if fs_entries.contains_key(path) {
                continue;
            }
            let still_needed = expected.kind == NodeKind::Dir && fs_entries.keys().any(|p| p.starts_with(&format!("{path}/")));
            if !still_needed {
                b.remove_path(path, expected);
            }
        }

        let mut wc = Change {
            change_id: old_wc.change_id,
            deps: vec![],
            author: self.author(),
            hlc: old_wc.hlc,
            message: old_wc.message.clone(),
            tree_ops: b.tree_ops,
            edits: b.edits,
            kind: ChangeKind::WorkingCopy,
        };
        let base_heads = base.maximal(&old_wc.deps);
        let mut deps: BTreeSet<ChangeHash> = base_heads.into_iter().collect();
        deps.extend(referenced_changes(&wc, &base));
        deps.extend(b.contributors.iter().copied());
        wc.deps = deps.into_iter().collect();
        wc.normalize();
        let resolves = b.resolves;

        let mut statuses = b.statuses;
        statuses.sort_by(|a, b| a.path.cmp(&b.path));
        // Empty snapshot: hash the candidate before storing; only record an op on change.
        let new_hash = wc.hash();
        let changed = new_hash != old_hash;
        if changed {
            self.store.put_change(&wc)?;
            let mut view = op.view.clone();
            view.workspaces.insert(self.workspace, new_hash);
            self.record_op(&[op_ref], &format!("{command}{SNAPSHOT_SUFFIX}"), view)?;
        }
        Ok(SnapshotResult { wc_hash: new_hash, wc, base, base_snapshot, statuses, changed, resolves })
    }

    /// Turn the working-copy change into a normal change on the bookmark (spec §12.3).
    pub fn commit(&self, message: &str, extra_deps: &[ChangeHash]) -> Result<ChangeHash> {
        let snap = self.snapshot("oxy commit")?;
        if snap.wc.tree_ops.is_empty() && snap.wc.edits.is_empty() {
            return fail("nothing to commit: the working copy matches its base");
        }
        if let Some(s) = snap.statuses.iter().find(|s| s.status == ChangeStatus::ConflictEdited) {
            return fail(format!("{} still contains conflict markers", s.path));
        }
        if message.trim().is_empty() {
            return fail("a commit message is required");
        }
        let (op_ref, op) = self.head_op()?;
        let mut deps: BTreeSet<ChangeHash> = referenced_changes(&snap.wc, &snap.base);
        if snap.resolves {
            // A resolution depends on every change that contributed to the
            // conflict (spec §8.1); those are already among the working copy's
            // dependencies, so keep every one that is not merely a base head.
            let heads: BTreeSet<ChangeHash> = snap.base.maximal(&snap.wc.deps).into_iter().collect();
            deps.extend(snap.wc.deps.iter().filter(|d| !heads.contains(d) || touches_conflict(&snap)).copied());
        }
        for d in extra_deps {
            if !snap.base.contains(d) {
                return fail(format!("--depends-on {d}: not in the working copy's base state"));
            }
            deps.insert(*d);
        }
        if self.config.sign_changes && self.secret_key()?.is_none() {
            return fail("core.sign is \"change\" but no secret key is available for author.key");
        }
        let mut change = Change {
            change_id: snap.wc.change_id,
            deps: deps.into_iter().collect(),
            author: self.author(),
            hlc: Hlc::now(),
            message: message.trim_end().to_string(),
            tree_ops: snap.wc.tree_ops.clone(),
            edits: snap.wc.edits.clone(),
            kind: if snap.resolves { ChangeKind::Resolution } else { ChangeKind::Normal },
        };
        change.normalize();
        let hash = self.store.put_change(&change)?;
        if self.config.sign_changes {
            self.sign_change(&hash)?;
        }

        // New bookmark heads: maximal elements of old heads plus the new change.
        // The working copy continues on its own base plus the new change, which
        // is exactly what the files on disk contain; the bookmark may hold
        // other heads (and conflicts) the working copy has not checked out.
        let old_heads = self.heads_of(&op.view, &self.config.bookmark)?;
        let old_base = snap.base.maximal(&snap.wc.deps);
        let mut all: Vec<ChangeHash> = old_heads.clone();
        all.extend(old_base.iter().copied());
        all.push(hash);
        let mut st = self.load_state(&all)?;
        st.add(change)?;
        let mut with_new = old_heads.clone();
        with_new.push(hash);
        let new_heads = st.maximal(&with_new);
        let mut wc_base = old_base.clone();
        wc_base.push(hash);
        let wc_base = st.maximal(&wc_base);

        let wc = self.new_working_copy(wc_base, "");
        let wc_hash = self.store.put_change(&wc)?;
        let mut view = op.view.clone();
        view.bookmarks.insert(self.config.bookmark.clone(), self.store.put_state(&StateObject::new(new_heads))?);
        view.workspaces.insert(self.workspace, wc_hash);
        self.record_op(&[op_ref], &format!("oxy commit -m {message:?}"), view)?;
        Ok(hash)
    }

    /// Move the working copy to the state whose heads are `heads` (spec §12.3):
    /// the working directory is rewritten to that state and a fresh
    /// working-copy change is started on it. The bookmark does not move.
    pub fn checkout(&self, heads: &[ChangeHash], discard: bool, command: &str) -> Result<CheckoutReport> {
        let snap = self.snapshot(command)?;
        if !discard && (!snap.wc.tree_ops.is_empty() || !snap.wc.edits.is_empty()) {
            return fail("the working copy has changes; commit them first or pass --discard");
        }
        let target_state = self.load_state(heads)?;
        let heads = target_state.maximal(heads);
        let target = target_state.materialize();
        let current = self.walk_working_copy()?;
        let mut report = CheckoutReport::default();

        // Remove tracked paths that the target does not have.
        let mut dirs_to_prune: BTreeSet<PathBuf> = BTreeSet::new();
        for path in current.keys() {
            if !target.files.contains_key(path) {
                let full = self.safe_path(path)?;
                fs::remove_file(&full)?;
                report.removed += 1;
                if let Some(parent) = full.parent() {
                    dirs_to_prune.insert(parent.to_path_buf());
                }
            }
        }
        // Write target files that differ.
        for (path, f) in &target.files {
            match &f.content {
                FileContent::Dir => continue,
                FileContent::Text { bytes, .. } => {
                    let same = current.get(path).is_some_and(|c| c.kind == NodeKind::File && &c.content == bytes && c.exec == f.mode.exec);
                    if !same {
                        self.write_file(path, bytes, f.mode.exec)?;
                        report.written += 1;
                    }
                }
                FileContent::Opaque { blobs } => {
                    let Some(blob) = blobs.first() else { continue };
                    let bytes = self.read_blob(blob)?;
                    if f.kind == NodeKind::Symlink {
                        let same = current.get(path).is_some_and(|c| c.kind == NodeKind::Symlink && c.content == bytes);
                        if !same {
                            self.write_symlink(path, &bytes)?;
                            report.written += 1;
                        }
                    } else {
                        let same = current.get(path).is_some_and(|c| c.kind == NodeKind::File && c.content == bytes && c.exec == f.mode.exec);
                        if !same {
                            self.write_file(path, &bytes, f.mode.exec)?;
                            report.written += 1;
                        }
                    }
                    if blobs.len() > 1 {
                        for (i, b) in blobs.iter().enumerate().skip(1) {
                            self.write_file(&format!("{path}.oxy-conflict-{}", i + 1), &self.read_blob(b)?, f.mode.exec)?;
                        }
                    }
                }
            }
        }
        // Prune directories left empty, deepest first.
        for d in dirs_to_prune.iter().rev() {
            let mut d = d.clone();
            while d != self.root && fs::read_dir(&d).map(|mut i| i.next().is_none()).unwrap_or(false) {
                fs::remove_dir(&d)?;
                let Some(p) = d.parent() else { break };
                d = p.to_path_buf();
            }
        }

        let (op_ref, op) = self.head_op()?;
        let wc = self.new_working_copy(heads, "");
        let wc_hash = self.store.put_change(&wc)?;
        let mut view = op.view.clone();
        view.workspaces.insert(self.workspace, wc_hash);
        self.record_op(&[op_ref], command, view)?;
        report.conflicted = target.is_conflicted();
        Ok(report)
    }

    /// The absolute path for a repository path, refusing anything that would
    /// escape the workspace or write through a symlink (spec §7.7).
    fn safe_path(&self, rel: &str) -> Result<PathBuf> {
        let mut full = self.root.clone();
        let comps: Vec<&str> = rel.split('/').collect();
        for (i, comp) in comps.iter().enumerate() {
            if comp.is_empty() || *comp == "." || *comp == ".." || comp.contains('\\') {
                return fail(format!("refusing unsafe path {rel:?}"));
            }
            if i == 0 && *comp == OXY_DIR {
                return fail(format!("refusing to write inside {OXY_DIR}: {rel:?}"));
            }
            if i + 1 < comps.len() {
                full.push(comp);
                if let Ok(m) = fs::symlink_metadata(&full) {
                    if m.file_type().is_symlink() {
                        return fail(format!("refusing to write through symlink {}", full.display()));
                    }
                }
            } else {
                full.push(comp);
            }
        }
        Ok(full)
    }

    fn write_file(&self, rel: &str, bytes: &[u8], exec: bool) -> Result<()> {
        let full = self.safe_path(rel)?;
        if let Some(parent) = full.parent() {
            fs::create_dir_all(parent)?;
        }
        if fs::symlink_metadata(&full).is_ok_and(|m| m.file_type().is_symlink() || m.is_dir()) {
            remove_any(&full)?;
        }
        fs::write(&full, bytes)?;
        set_executable(&full, exec)?;
        Ok(())
    }

    fn write_symlink(&self, rel: &str, target: &[u8]) -> Result<()> {
        let full = self.safe_path(rel)?;
        if let Some(parent) = full.parent() {
            fs::create_dir_all(parent)?;
        }
        if fs::symlink_metadata(&full).is_ok() {
            remove_any(&full)?;
        }
        #[cfg(unix)]
        {
            std::os::unix::fs::symlink(String::from_utf8_lossy(target).as_ref(), &full)?;
            Ok(())
        }
        #[cfg(not(unix))]
        {
            // Spec §7.7: without symlink support, write the target as a plain file.
            fs::write(&full, target)?;
            Ok(())
        }
    }

    /// Changes reachable from the bookmark and the working copy, newest first.
    pub fn log(&self) -> Result<Vec<LogEntry>> {
        let (wc_hash, _) = self.working_copy()?;
        let mut heads = self.bookmark_heads()?;
        heads.push(wc_hash);
        let state = self.load_state(&heads)?;
        let head_set: BTreeSet<ChangeHash> = self.bookmark_heads()?.into_iter().collect();
        let mut entries: Vec<LogEntry> = state
            .changes()
            .map(|(h, c)| LogEntry { hash: *h, change: c.clone(), is_working_copy: *h == wc_hash, is_head: head_set.contains(h) })
            .collect();
        entries.sort_by(|a, b| b.is_working_copy.cmp(&a.is_working_copy).then(b.change.hlc.cmp(&a.change.hlc)).then(b.hash.cmp(&a.hash)));
        Ok(entries)
    }

    /// Resolve a change by ChangeId prefix, `#hash` prefix, `@` (working copy), or bookmark.
    pub fn resolve_change(&self, spec: &str) -> Result<ChangeHash> {
        if spec == "@" {
            return Ok(self.working_copy()?.0);
        }
        if spec.is_empty() || spec == "#" {
            return fail("empty change specifier");
        }
        let entries = self.log()?;
        let matches: Vec<&LogEntry> = if let Some(hp) = spec.strip_prefix('#') {
            entries.iter().filter(|e| e.hash.starts_with_hex(hp)).collect()
        } else {
            entries.iter().filter(|e| e.change.change_id.starts_with_hex(spec)).collect()
        };
        match matches.len() {
            1 => Ok(matches[0].hash),
            0 => fail(format!("no change matches {spec:?}")),
            _ => {
                let ids: BTreeSet<ChangeId> = matches.iter().map(|e| e.change.change_id).collect();
                if ids.len() == 1 {
                    fail(format!("change {spec} is divergent: {} variants", matches.len()))
                } else {
                    fail(format!("{spec:?} is ambiguous"))
                }
            }
        }
    }

    /// Human-readable description of what a change does, with line content.
    pub fn describe_change(&self, hash: &ChangeHash) -> Result<String> {
        let change = self.store.get_change(hash)?;
        let base = self.load_state(&change.deps)?;
        let base_snapshot = base.materialize();
        Ok(render_change(&change, &base, &base_snapshot))
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PullReport {
    pub heads: Vec<ChangeHash>,
    pub changed: bool,
    pub checked_out: bool,
}

#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct CheckoutReport {
    pub written: usize,
    pub removed: usize,
    pub conflicted: bool,
}

fn remove_any(path: &Path) -> std::io::Result<()> {
    let m = fs::symlink_metadata(path)?;
    if m.is_dir() { fs::remove_dir_all(path) } else { fs::remove_file(path) }
}

#[cfg(unix)]
fn set_executable(path: &Path, exec: bool) -> std::io::Result<()> {
    use std::os::unix::fs::PermissionsExt;
    let mut perms = fs::metadata(path)?.permissions();
    let mode = perms.mode();
    let want = if exec { mode | 0o111 } else { mode & !0o111 };
    if want != mode {
        perms.set_mode(want);
        fs::set_permissions(path, perms)?;
    }
    Ok(())
}
#[cfg(not(unix))]
fn set_executable(_path: &Path, _exec: bool) -> std::io::Result<()> {
    Ok(())
}

#[cfg(unix)]
fn is_executable(m: &fs::Metadata) -> bool {
    use std::os::unix::fs::PermissionsExt;
    m.permissions().mode() & 0o111 != 0
}
#[cfg(not(unix))]
fn is_executable(_m: &fs::Metadata) -> bool {
    false
}

fn op_ref(k: OpKey) -> OpRef {
    OpRef { change: k.0, index: k.1 }
}

fn split_path(path: &str) -> (&str, &str) {
    match path.rfind('/') {
        Some(i) => (&path[..i], &path[i + 1..]),
        None => ("", path),
    }
}

/// Builds the tree ops and edits of a working-copy change against a base.
struct ChangeBuilder<'a> {
    base: &'a State,
    base_snapshot: &'a Snapshot,
    tree_ops: Vec<TreeOp>,
    edits: Vec<Edit>,
    statuses: Vec<PathStatus>,
    dir_nodes: HashMap<String, NodeId>,
    reuse: HashMap<String, (NodeId, NodeKind)>,
    /// Changes that contributed to conflicts this working copy resolves.
    contributors: BTreeSet<ChangeHash>,
    resolves: bool,
}

impl<'a> ChangeBuilder<'a> {
    fn new(base: &'a State, base_snapshot: &'a Snapshot, reuse: HashMap<String, (NodeId, NodeKind)>) -> Self {
        let mut dir_nodes: HashMap<String, NodeId> = HashMap::new();
        dir_nodes.insert(String::new(), NodeId::ROOT);
        for (p, f) in &base_snapshot.files {
            if f.kind == NodeKind::Dir {
                dir_nodes.insert(p.clone(), f.node);
            }
        }
        ChangeBuilder { base, base_snapshot, tree_ops: vec![], edits: vec![], statuses: vec![], dir_nodes, reuse, contributors: BTreeSet::new(), resolves: false }
    }

    fn reused_node(&self, path: &str, kind: NodeKind) -> Option<NodeId> {
        self.reuse.get(path).filter(|(_, k)| *k == kind).map(|(n, _)| *n)
    }

    fn ensure_dir(&mut self, path: &str) -> NodeId {
        if let Some(n) = self.dir_nodes.get(path) {
            return *n;
        }
        let mut parent = NodeId::ROOT;
        let mut prefix = String::new();
        for comp in path.split('/') {
            if !prefix.is_empty() {
                prefix.push('/');
            }
            prefix.push_str(comp);
            parent = match self.dir_nodes.get(&prefix) {
                Some(n) => *n,
                None => {
                    let node = self.reused_node(&prefix, NodeKind::Dir).unwrap_or_else(NodeId::random);
                    self.tree_ops.push(TreeOp::AddNode { node, kind: NodeKind::Dir, mode: Mode::default(), parent, name: comp.to_string() });
                    self.dir_nodes.insert(prefix.clone(), node);
                    node
                }
            };
        }
        parent
    }

    fn add_path(&mut self, repo: &Repo, path: &str, e: &FsEntry) -> Result<()> {
        let (dir, name) = split_path(path);
        let parent = self.ensure_dir(dir);
        let node = self.reused_node(path, e.kind).unwrap_or_else(NodeId::random);
        let opaque = e.kind == NodeKind::Symlink || is_binary(&e.content);
        self.tree_ops.push(TreeOp::AddNode { node, kind: e.kind, mode: Mode { exec: e.exec, opaque }, parent, name: name.to_string() });
        if opaque {
            let blob = repo.store_blob(&e.content)?;
            self.edits.push(Edit::Replace { node, old: None, new: Some(blob) });
        } else if !e.content.is_empty() {
            self.edits.push(Edit::Insert {
                node,
                after: crate::objects::AtomRef::Start,
                before: crate::objects::AtomRef::End,
                lines: split_lines(&e.content).iter().map(|l| l.to_vec()).collect(),
            });
        }
        self.statuses.push(PathStatus { path: path.to_string(), status: ChangeStatus::Added });
        Ok(())
    }

    fn remove_path(&mut self, path: &str, expected: &crate::state::FileState) {
        let entry = &self.base_snapshot.tree.entries[path];
        self.tree_ops.push(TreeOp::RemoveNode { node: expected.node, placement: op_ref(entry.placement) });
        if path.contains(".oxy-conflict-") || expected.is_conflicted() {
            self.resolves = true;
        }
        self.statuses.push(PathStatus { path: path.to_string(), status: ChangeStatus::Removed });
    }

    fn update_path(&mut self, repo: &Repo, path: &str, e: &FsEntry, expected: &crate::state::FileState) -> Result<()> {
        if expected.kind != e.kind {
            self.remove_path(path, expected);
            self.statuses.pop();
            self.add_path(repo, path, e)?;
            self.statuses.pop();
            self.statuses.push(PathStatus { path: path.to_string(), status: ChangeStatus::Modified });
            return Ok(());
        }
        let entry = &self.base_snapshot.tree.entries[path];
        let node = expected.node;
        let mode_atom = entry.mode_atom.map(op_ref);
        let mut status: Option<ChangeStatus> = None;
        match &expected.content {
            FileContent::Dir => {}
            FileContent::Text { bytes, materialized } => {
                if materialized.is_conflicted() {
                    if bytes == &e.content {
                        return Ok(());
                    }
                    if has_conflict_markers(&e.content) {
                        self.statuses.push(PathStatus { path: path.to_string(), status: ChangeStatus::ConflictEdited });
                        return Ok(());
                    }
                    // Resolution (spec §9.6): diff against the unconflicted lines
                    // with each region as a gap, then retire every region atom.
                    // Whatever the author kept from a region is re-inserted as
                    // new atoms, which leaves the graph totally ordered.
                    let regions = self.base.conflict_regions(&node);
                    let mut edits = text_edits(node, &regions.plain, &e.content);
                    if !regions.region_atoms.is_empty() {
                        edits.insert(0, Edit::Delete { node, atoms: ranges(&regions.region_atoms) });
                    }
                    self.edits.extend(edits);
                    self.contributors.extend(regions.contributors);
                    self.resolves = true;
                    if e.exec != expected.mode.exec {
                        if let Some(old) = mode_atom {
                            self.tree_ops.push(TreeOp::SetMode { node, old, mode: Mode { exec: e.exec, opaque: false } });
                        }
                    }
                    self.statuses.push(PathStatus { path: path.to_string(), status: ChangeStatus::Resolved });
                    return Ok(());
                }
                if bytes != &e.content {
                    if is_binary(&e.content) {
                        // Text → opaque (spec §7.5).
                        if let Some(old) = mode_atom {
                            self.tree_ops.push(TreeOp::SetMode { node, old, mode: Mode { exec: e.exec, opaque: true } });
                        }
                        let live: Vec<_> = repo_live_keys(self.base, &node);
                        if !live.is_empty() {
                            self.edits.push(Edit::Delete { node, atoms: ranges(&live) });
                        }
                        let blob = repo.store_blob(&e.content)?;
                        self.edits.push(Edit::Replace { node, old: None, new: Some(blob) });
                        status = Some(ChangeStatus::Modified);
                    } else {
                        let old = self.base.live_lines(&node);
                        let edits = text_edits(node, &old, &e.content);
                        if !edits.is_empty() {
                            self.edits.extend(edits);
                            status = Some(ChangeStatus::Modified);
                        }
                    }
                }
                let switched_to_opaque = status == Some(ChangeStatus::Modified) && is_binary(&e.content);
                if !switched_to_opaque && e.exec != expected.mode.exec {
                    if let Some(old) = mode_atom {
                        self.tree_ops.push(TreeOp::SetMode { node, old, mode: Mode { exec: e.exec, opaque: false } });
                        status.get_or_insert(ChangeStatus::ModeChanged);
                    }
                }
            }
            FileContent::Opaque { blobs } => {
                let new_ref = Repo::blob_ref(&e.content);
                if blobs.len() > 1 {
                    if !blobs.contains(&new_ref) {
                        self.statuses.push(PathStatus { path: path.to_string(), status: ChangeStatus::ConflictEdited });
                    }
                    return Ok(());
                }
                let current = blobs.first().copied();
                if current != Some(new_ref) {
                    if e.kind == NodeKind::File && !is_binary(&e.content) {
                        // Opaque → text (spec §7.5).
                        if let Some(old) = mode_atom {
                            self.tree_ops.push(TreeOp::SetMode { node, old, mode: Mode { exec: e.exec, opaque: false } });
                        }
                        self.edits.push(Edit::Replace { node, old: current, new: None });
                        if !e.content.is_empty() {
                            self.edits.push(Edit::Insert {
                                node,
                                after: crate::objects::AtomRef::Start,
                                before: crate::objects::AtomRef::End,
                                lines: split_lines(&e.content).iter().map(|l| l.to_vec()).collect(),
                            });
                        }
                    } else {
                        let blob = repo.store_blob(&e.content)?;
                        self.edits.push(Edit::Replace { node, old: current, new: Some(blob) });
                    }
                    status = Some(ChangeStatus::Modified);
                } else if e.kind == NodeKind::File && e.exec != expected.mode.exec {
                    if let Some(old) = mode_atom {
                        self.tree_ops.push(TreeOp::SetMode { node, old, mode: Mode { exec: e.exec, opaque: true } });
                        status = Some(ChangeStatus::ModeChanged);
                    }
                }
            }
        }
        if let Some(s) = status {
            self.statuses.push(PathStatus { path: path.to_string(), status: s });
        }
        Ok(())
    }
}

/// Whether a working copy touches a node that is conflicted in its base.
fn touches_conflict(snap: &SnapshotResult) -> bool {
    let conflicted: BTreeSet<NodeId> = snap.base_snapshot.files.values().filter(|f| f.is_conflicted()).map(|f| f.node).collect();
    snap.wc.tree_ops.iter().any(|op| conflicted.contains(&op.node())) || snap.wc.edits.iter().any(|e| conflicted.contains(&e.node()))
}

fn repo_live_keys(base: &State, node: &NodeId) -> Vec<crate::graph::AtomKey> {
    base.live_lines(node).into_iter().map(|(k, _)| k).collect()
}

/// The changes a change's scope references (spec §8.1): introducers of every
/// atom, placement, and mode it touches, and of every node it operates on.
pub fn referenced_changes(change: &Change, base: &State) -> BTreeSet<ChangeHash> {
    let mut out = BTreeSet::new();
    let opref = |r: &OpRef, out: &mut BTreeSet<ChangeHash>| {
        if !r.change.is_zero() {
            out.insert(r.change);
        }
    };
    let mut nodes: Vec<NodeId> = Vec::new();
    for op in &change.tree_ops {
        match op {
            TreeOp::AddNode { parent, .. } => nodes.push(*parent),
            TreeOp::RemoveNode { node, placement } => {
                nodes.push(*node);
                opref(placement, &mut out);
            }
            TreeOp::Move { node, old, parent, .. } => {
                nodes.push(*node);
                nodes.push(*parent);
                opref(old, &mut out);
            }
            TreeOp::SetMode { node, old, .. } => {
                nodes.push(*node);
                opref(old, &mut out);
            }
        }
    }
    for e in &change.edits {
        nodes.push(e.node());
        match e {
            Edit::Insert { after, before, .. } => {
                for r in [after, before] {
                    if let crate::objects::AtomRef::Atom { change, .. } = r {
                        if !change.is_zero() {
                            out.insert(*change);
                        }
                    }
                }
            }
            Edit::Delete { atoms, .. } => {
                for r in atoms {
                    if !r.change.is_zero() {
                        out.insert(r.change);
                    }
                }
            }
            Edit::Replace { .. } => {}
        }
    }
    for n in nodes {
        if let Some(h) = base.tree().introducer(&n) {
            out.insert(h);
        }
    }
    out
}

/// Paths of the nodes a change adds on top of `base_snapshot`.
pub fn added_node_paths(change: &Change, base_snapshot: &Snapshot) -> HashMap<String, (NodeId, NodeKind)> {
    let by_node = base_snapshot.tree.by_node();
    let mut new_names: HashMap<NodeId, (NodeId, String, NodeKind)> = HashMap::new();
    for op in &change.tree_ops {
        if let TreeOp::AddNode { node, parent, name, kind, .. } = op {
            new_names.insert(*node, (*parent, name.clone(), *kind));
        }
    }
    let mut out = HashMap::new();
    for (node, (_, _, kind)) in &new_names {
        if let Some(path) = path_of_node(node, &by_node, &new_names) {
            out.insert(path, (*node, *kind));
        }
    }
    out
}

fn path_of_node(
    n: &NodeId,
    by_node: &HashMap<NodeId, &crate::tree::TreeEntry>,
    new_names: &HashMap<NodeId, (NodeId, String, NodeKind)>,
) -> Option<String> {
    if let Some(e) = by_node.get(n) {
        return Some(e.path.clone());
    }
    let mut parts = Vec::new();
    let mut cur = *n;
    loop {
        if cur.is_root() {
            break;
        }
        if let Some(e) = by_node.get(&cur) {
            if !e.path.is_empty() {
                parts.push(e.path.clone());
            }
            break;
        }
        let (parent, name, _) = new_names.get(&cur)?;
        parts.push(name.clone());
        cur = *parent;
    }
    parts.reverse();
    Some(parts.join("/"))
}

/// Render a change's operations with line content, using `base` for deleted lines.
pub fn render_change(change: &Change, base: &State, base_snapshot: &Snapshot) -> String {
    let by_node = base_snapshot.tree.by_node();
    let mut new_names: HashMap<NodeId, (NodeId, String, NodeKind)> = HashMap::new();
    for op in &change.tree_ops {
        if let TreeOp::AddNode { node, parent, name, kind, .. } = op {
            new_names.insert(*node, (*parent, name.clone(), *kind));
        }
    }
    let path_of = |n: &NodeId| -> String { path_of_node(n, &by_node, &new_names).unwrap_or_else(|| format!("<node {}>", n.short(8))) };

    let mut out = String::new();
    for op in &change.tree_ops {
        match op {
            TreeOp::AddNode { node, kind, mode, .. } => {
                out.push_str(&format!("A {} ({:?}{}{})\n", path_of(node), kind, if mode.exec { ", exec" } else { "" }, if mode.opaque { ", opaque" } else { "" }));
            }
            TreeOp::RemoveNode { node, .. } => out.push_str(&format!("D {}\n", path_of(node))),
            TreeOp::Move { node, name, .. } => out.push_str(&format!("R {} -> {}\n", path_of(node), name)),
            TreeOp::SetMode { node, mode, .. } => {
                out.push_str(&format!("M {} mode: exec={} opaque={}\n", path_of(node), mode.exec, mode.opaque));
            }
        }
    }
    let mut last_node: Option<NodeId> = None;
    for e in &change.edits {
        let n = e.node();
        if last_node != Some(n) {
            out.push_str(&format!("--- {}\n", path_of(&n)));
            last_node = Some(n);
        }
        match e {
            Edit::Insert { lines, .. } => {
                for l in lines {
                    out.push('+');
                    out.push_str(&String::from_utf8_lossy(l));
                    if !l.ends_with(b"\n") {
                        out.push('\n');
                    }
                }
            }
            Edit::Delete { atoms, .. } => {
                for r in atoms {
                    for i in r.from..r.to {
                        let content = base.file(&n).and_then(|g| g.content(&(r.change, i))).unwrap_or(b"<unknown>\n");
                        out.push('-');
                        out.push_str(&String::from_utf8_lossy(content));
                        if !content.ends_with(b"\n") {
                            out.push('\n');
                        }
                    }
                }
            }
            Edit::Replace { old, new, .. } => {
                out.push_str(&format!(
                    "  opaque content {} -> {}\n",
                    old.map(|o| o.short(12)).unwrap_or_else(|| "none".into()),
                    new.map(|o| o.short(12)).unwrap_or_else(|| "none".into())
                ));
            }
        }
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;

    fn write(root: &Path, rel: &str, content: &[u8]) {
        let p = root.join(rel);
        fs::create_dir_all(p.parent().unwrap()).unwrap();
        fs::write(p, content).unwrap();
    }

    fn statuses(s: &SnapshotResult) -> Vec<(String, ChangeStatus)> {
        s.statuses.iter().map(|p| (p.path.clone(), p.status)).collect()
    }

    #[test]
    fn init_snapshot_commit_log_undo() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let repo = Repo::init(root).unwrap();
        assert!(Repo::init(root).is_err());
        let ops = repo.op_log().unwrap();
        assert_eq!(ops.len(), 1);
        assert_eq!(ops[0].1.command, "oxy init");

        // Empty working copy: snapshot records no operation (spec §12.3).
        let s = repo.snapshot("oxy status").unwrap();
        assert!(!s.changed);
        assert_eq!(repo.op_log().unwrap().len(), 1);

        write(root, "src/main.rs", b"fn main() {}\n");
        write(root, "README.md", b"# Hello\n");
        write(root, ".oxyignore", b"/target\n");
        write(root, "target/junk.o", b"\0\0\0");
        let s = repo.snapshot("oxy status").unwrap();
        assert!(s.changed);
        assert_eq!(
            statuses(&s),
            vec![
                (".oxyignore".into(), ChangeStatus::Added),
                ("README.md".into(), ChangeStatus::Added),
                ("src/main.rs".into(), ChangeStatus::Added),
            ]
        );
        assert_eq!(repo.op_log().unwrap().len(), 2);
        // Snapshotting again with nothing changed records no op.
        let s2 = repo.snapshot("oxy status").unwrap();
        assert!(!s2.changed);
        assert_eq!(s2.wc_hash, s.wc_hash);
        assert_eq!(repo.op_log().unwrap().len(), 2);

        let h1 = repo.commit("Initial import", &[]).unwrap();
        let c1 = repo.store().get_change(&h1).unwrap();
        assert_eq!(c1.kind, ChangeKind::Normal);
        assert!(c1.deps.is_empty(), "first change has nothing to depend on");
        assert_eq!(repo.bookmark_heads().unwrap(), vec![h1]);
        let (wc_hash, wc) = repo.working_copy().unwrap();
        assert_eq!(wc.deps, vec![h1]);
        assert!(wc.edits.is_empty());
        assert!(repo.commit("nothing", &[]).is_err());

        // Modify one file, remove another, add a binary file.
        write(root, "src/main.rs", b"fn main() {\n    println!(\"hi\");\n}\n");
        fs::remove_file(root.join("README.md")).unwrap();
        write(root, "logo.png", b"\x89PNG\0\0\x01");
        let s = repo.snapshot("oxy status").unwrap();
        assert_eq!(
            statuses(&s),
            vec![
                ("README.md".into(), ChangeStatus::Removed),
                ("logo.png".into(), ChangeStatus::Added),
                ("src/main.rs".into(), ChangeStatus::Modified),
            ]
        );
        assert_ne!(s.wc_hash, wc_hash);
        // The rewritten working copy keeps its ChangeId and depends on h1.
        assert_eq!(s.wc.change_id, wc.change_id);
        assert!(s.wc.deps.contains(&h1));

        let h2 = repo.commit("Second", &[]).unwrap();
        let c2 = repo.store().get_change(&h2).unwrap();
        assert_eq!(c2.deps, vec![h1], "everything it touches was introduced by h1");
        assert_eq!(repo.bookmark_heads().unwrap(), vec![h2]);

        // The materialized head state matches the working copy.
        let st = repo.load_state(&[h2]).unwrap();
        let snap = st.materialize();
        assert!(!snap.is_conflicted());
        assert_eq!(snap.files.keys().cloned().collect::<Vec<_>>(), [".oxyignore", "logo.png", "src", "src/main.rs"]);
        assert!(matches!(&snap.files["src/main.rs"].content, FileContent::Text { bytes, .. } if bytes == b"fn main() {\n    println!(\"hi\");\n}\n"));
        assert!(snap.files["logo.png"].mode.opaque);
        if let FileContent::Opaque { blobs } = &snap.files["logo.png"].content {
            assert_eq!(repo.read_blob(&blobs[0]).unwrap(), b"\x89PNG\0\0\x01");
        } else {
            panic!("logo should be opaque");
        }

        // Log: newest first, working copy included.
        let log = repo.log().unwrap();
        assert_eq!(log.len(), 3);
        assert!(log[0].is_working_copy);
        assert_eq!(log[1].hash, h2);
        assert!(log[1].is_head);
        assert_eq!(log[2].hash, h1);
        let d = repo.describe_change(&h2).unwrap();
        assert!(d.contains("D README.md"), "{d}");
        assert!(d.contains("+    println!(\"hi\");"), "{d}");
        assert!(d.contains("-fn main() {}"), "{d}");

        // Resolution by prefix.
        assert_eq!(repo.resolve_change(&c2.change_id.short(6)).unwrap(), h2);
        assert_eq!(repo.resolve_change(&format!("#{}", h1.short(8))).unwrap(), h1);
        assert!(repo.resolve_change("zzzz").is_err());

        // Undo the commit: bookmark and working copy go back.
        repo.undo().unwrap();
        assert_eq!(repo.bookmark_heads().unwrap(), vec![h1]);
        let s = repo.snapshot("oxy status").unwrap();
        assert!(!s.changed, "files on disk still match the pre-commit working copy");
        assert_eq!(s.statuses.len(), 3);
    }

    /// Make `main` conflicted: two commits on the same base that edit the same line.
    fn conflicted_repo() -> (tempfile::TempDir, Repo, ChangeHash, ChangeHash, ChangeHash) {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let repo = Repo::init(root).unwrap();
        write(root, "f.txt", b"a\nb\nc\n");
        let h1 = repo.commit("base", &[]).unwrap();
        write(root, "f.txt", b"a\nB\nc\n");
        let h2 = repo.commit("upper", &[]).unwrap();
        repo.checkout(&[h1], false, "checkout").unwrap();
        write(root, "f.txt", b"a\nX\nc\n");
        let h3 = repo.commit("ex", &[]).unwrap();
        (dir, repo, h1, h2, h3)
    }

    #[test]
    fn concurrent_edits_conflict_and_can_be_resolved() {
        let (dir, repo, h1, h2, h3) = conflicted_repo();
        let root = dir.path();
        let heads: BTreeSet<_> = repo.bookmark_heads().unwrap().into_iter().collect();
        assert_eq!(heads, [h2, h3].into_iter().collect());
        let st = repo.load_state(&[h2, h3]).unwrap();
        assert!(st.materialize().is_conflicted());

        // Checking out main writes markers.
        let r = repo.checkout(&repo.bookmark_heads().unwrap(), false, "checkout main").unwrap();
        assert!(r.conflicted);
        let marked = fs::read_to_string(root.join("f.txt")).unwrap();
        assert!(marked.starts_with("a\n<<<<<<< oxy conflict 1 of 1"), "{marked}");
        assert!(marked.contains("B\n") && marked.contains("X\n") && marked.ends_with("end\nc\n"), "{marked}");
        assert!(has_conflict_markers(marked.as_bytes()));
        // Untouched markers: clean working copy; commit has nothing to do.
        let s = repo.snapshot("status").unwrap();
        assert!(s.statuses.is_empty());
        assert!(!s.resolves);

        // Partially edited file that still has markers cannot be committed.
        write(root, "f.txt", marked.replace("B\n", "BB\n").as_bytes());
        let s = repo.snapshot("status").unwrap();
        assert_eq!(statuses(&s), vec![("f.txt".into(), ChangeStatus::ConflictEdited)]);
        assert!(repo.commit("no", &[]).is_err());

        // Resolve by keeping one side and adding a line elsewhere.
        write(root, "f.txt", b"a\nX\nc\nd\n");
        let s = repo.snapshot("status").unwrap();
        assert_eq!(statuses(&s), vec![("f.txt".into(), ChangeStatus::Resolved)]);
        assert!(s.resolves);
        let h4 = repo.commit("resolve", &[]).unwrap();
        let c4 = repo.store().get_change(&h4).unwrap();
        assert_eq!(c4.kind, ChangeKind::Resolution);
        assert!(c4.deps.contains(&h2) && c4.deps.contains(&h3) && c4.deps.contains(&h1), "{:?}", c4.deps);
        assert_eq!(repo.bookmark_heads().unwrap(), vec![h4]);
        let snap = repo.load_state(&[h4]).unwrap().materialize();
        assert!(!snap.is_conflicted());
        assert!(matches!(&snap.files["f.txt"].content, FileContent::Text { bytes, .. } if bytes == b"a\nX\nc\nd\n"));
        assert!(!repo.snapshot("status").unwrap().changed);
        // A peer holding only h2 and h3 and receiving h4 sees the same result,
        // whatever order the changes arrive in.
        let mut st = State::new();
        for h in [h4, h3, h1, h2] {
            st.add_unchecked(repo.store().get_change(&h).unwrap());
        }
        st.validate().unwrap();
        assert!(matches!(&st.materialize().files["f.txt"].content, FileContent::Text { bytes, .. } if bytes == b"a\nX\nc\nd\n"));
    }

    #[test]
    fn resolution_may_keep_both_sides_or_neither() {
        let (dir, repo, _h1, _h2, _h3) = conflicted_repo();
        let root = dir.path();
        repo.checkout(&repo.bookmark_heads().unwrap(), false, "checkout main").unwrap();
        // Keep both sides in a chosen order.
        write(root, "f.txt", b"a\nX\nB\nc\n");
        let h = repo.commit("both", &[]).unwrap();
        let snap = repo.load_state(&[h]).unwrap().materialize();
        assert!(!snap.is_conflicted());
        assert!(matches!(&snap.files["f.txt"].content, FileContent::Text { bytes, .. } if bytes == b"a\nX\nB\nc\n"));
        // Undo and instead drop the whole region.
        repo.undo().unwrap();
        write(root, "f.txt", b"a\nc\n");
        let h = repo.commit("neither", &[]).unwrap();
        let snap = repo.load_state(&[h]).unwrap().materialize();
        assert!(!snap.is_conflicted());
        assert!(matches!(&snap.files["f.txt"].content, FileContent::Text { bytes, .. } if bytes == b"a\nc\n"));
    }

    #[test]
    fn name_conflict_resolved_by_removing_a_candidate() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let repo = Repo::init(root).unwrap();
        write(root, "keep.txt", b"k\n");
        let h1 = repo.commit("base", &[]).unwrap();
        write(root, "new.txt", b"one\n");
        repo.commit("one", &[]).unwrap();
        repo.checkout(&[h1], false, "checkout").unwrap();
        write(root, "new.txt", b"two\n");
        repo.commit("two", &[]).unwrap();
        let r = repo.checkout(&repo.bookmark_heads().unwrap(), false, "checkout main").unwrap();
        assert!(r.conflicted);
        assert!(root.join("new.txt.oxy-conflict-1").exists() && root.join("new.txt.oxy-conflict-2").exists());
        assert!(!root.join("new.txt").exists());
        // Keep candidate 2 under the real name.
        fs::remove_file(root.join("new.txt.oxy-conflict-1")).unwrap();
        fs::rename(root.join("new.txt.oxy-conflict-2"), root.join("new.txt")).unwrap();
        let h = repo.commit("pick two", &[]).unwrap();
        assert_eq!(repo.store().get_change(&h).unwrap().kind, ChangeKind::Resolution);
        // The resolution does not touch keep.txt, so it does not depend on h1;
        // the bookmark keeps both as heads and their union is the state.
        let heads: BTreeSet<_> = repo.bookmark_heads().unwrap().into_iter().collect();
        assert_eq!(heads, [h1, h].into_iter().collect());
        let snap = repo.load_state(&repo.bookmark_heads().unwrap()).unwrap().materialize();
        assert!(!snap.is_conflicted(), "{:?}", snap.tree.conflicts);
        assert_eq!(snap.files.keys().cloned().collect::<Vec<_>>(), ["keep.txt", "new.txt"]);
        assert!(matches!(&snap.files["new.txt"].content, FileContent::Text { bytes, .. } if bytes == b"two\n"));
    }

    #[test]
    fn identities_and_signed_commits() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let mut repo = Repo::init(root).unwrap().with_keys_dir(root.join("keys"));
        write(root, "a.txt", b"a\n");
        let h0 = repo.commit("unsigned", &[]).unwrap();
        assert_eq!(repo.verify_change(&h0).unwrap(), SignatureStatus::Unsigned);
        assert_eq!(repo.store().get_change(&h0).unwrap().author, ObjectRef::ZERO);

        let (key, id) = repo.create_identity("Ada", "[email protected]").unwrap();
        assert_eq!(id.hash(), key);
        assert_eq!(repo.config.author_key, Some(key));
        // Config survives reopen; the secret key is found again.
        let reopened = Repo::open(root).unwrap().with_keys_dir(root.join("keys"));
        assert_eq!(reopened.config.author_key, Some(key));
        assert_eq!(reopened.secret_key().unwrap().unwrap().0, key);

        // Default core.sign = seal: commits carry the author but no signature.
        write(root, "a.txt", b"a\nb\n");
        let h1 = repo.commit("authored", &[]).unwrap();
        assert_eq!(repo.store().get_change(&h1).unwrap().author, key);
        assert_eq!(repo.verify_change(&h1).unwrap(), SignatureStatus::Unsigned);
        // Signing later works too.
        repo.sign_change(&h1).unwrap();
        assert!(matches!(repo.verify_change(&h1).unwrap(), SignatureStatus::Valid { key: k, .. } if k == key));

        repo.config.set("core.sign", "change").unwrap();
        repo.save_config().unwrap();
        write(root, "a.txt", b"a\nb\nc\n");
        let h2 = repo.commit("signed", &[]).unwrap();
        assert_eq!(repo.verify_change(&h2).unwrap(), SignatureStatus::Valid { key, name: "Ada".into(), email: "[email protected]".into(), sealed: false });

        // A signature by a key that is not the author or a delegate is rejected.
        let other = SecretKey::generate();
        let other_id = other.identity("Mallory", "[email protected]", 0);
        let other_key = repo.store().put_identity(&other_id).unwrap();
        let forged = other.sign(Domain::Change, &other_key, &h0);
        repo.store().put_signature(&h0, &forged).unwrap();
        assert!(matches!(repo.verify_change(&h0).unwrap(), SignatureStatus::Invalid(m) if m.contains("neither the author")));

        // Tampering with the stored signature invalidates it.
        let mut sig = repo.store().signatures(&h2).unwrap().remove(0);
        sig.ed[0] ^= 1;
        repo.store().put_signature(&h2, &sig).unwrap();
        assert!(matches!(repo.verify_change(&h2).unwrap(), SignatureStatus::Invalid(_)));

        // Without the secret key, signing at commit fails cleanly.
        let no_keys = Repo::open(root).unwrap().with_keys_dir(root.join("nowhere"));
        write(root, "a.txt", b"z\n");
        assert!(no_keys.commit("cannot sign", &[]).is_err());
    }

    #[test]
    fn checkout_moves_the_working_copy() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let repo = Repo::init(root).unwrap();
        write(root, "a.txt", b"one\n");
        write(root, "sub/deep/b.txt", b"b\n");
        let h1 = repo.commit("first", &[]).unwrap();
        write(root, "a.txt", b"two\n");
        fs::remove_file(root.join("sub/deep/b.txt")).unwrap();
        write(root, "bin.dat", &[0, 1, 2, 3]);
        let h2 = repo.commit("second", &[]).unwrap();

        let r = repo.checkout(&[h1], false, "oxy checkout").unwrap();
        assert_eq!(r, CheckoutReport { written: 2, removed: 1, conflicted: false });
        assert_eq!(fs::read(root.join("a.txt")).unwrap(), b"one\n");
        assert_eq!(fs::read(root.join("sub/deep/b.txt")).unwrap(), b"b\n");
        assert!(!root.join("bin.dat").exists());
        let (_, wc) = repo.working_copy().unwrap();
        assert_eq!(wc.deps, vec![h1]);
        assert!(!repo.snapshot("status").unwrap().changed, "checkout leaves a clean working copy");
        // The bookmark still points at h2.
        assert_eq!(repo.bookmark_heads().unwrap(), vec![h2]);

        // Dirty working copy refuses without --discard.
        write(root, "a.txt", b"dirty\n");
        assert!(repo.checkout(&[h2], false, "oxy checkout").is_err());
        let r = repo.checkout(&[h2], true, "oxy checkout --discard").unwrap();
        assert_eq!(fs::read(root.join("a.txt")).unwrap(), b"two\n");
        assert_eq!(fs::read(root.join("bin.dat")).unwrap(), [0, 1, 2, 3]);
        assert!(!root.join("sub").exists(), "empty directories are pruned");
        assert_eq!(r.removed, 1);
        assert!(!repo.snapshot("status").unwrap().changed);

        // Refuses to write through a symlinked directory.
        #[cfg(unix)]
        {
            fs::remove_dir_all(root.join("sub")).ok();
            std::os::unix::fs::symlink("/tmp", root.join("sub")).unwrap();
            assert!(repo.checkout(&[h1], true, "oxy checkout").is_err());
        }
    }

    #[test]
    fn large_files_are_chunked_and_read_back() {
        let dir = tempfile::tempdir().unwrap();
        let repo = Repo::init(dir.path()).unwrap();
        let mut big = vec![0u8; 700 * 1024];
        for (i, b) in big.iter_mut().enumerate() {
            *b = (i as u32).wrapping_mul(2654435761).to_le_bytes()[0];
        }
        let r = repo.store_blob(&big).unwrap();
        let blob = Blob::decode(&repo.store().get_typed(&r, ObjectType::Blob).unwrap()).unwrap();
        assert!(blob.chunks.len() >= 3, "{}", blob.chunks.len());
        assert_eq!(repo.read_blob(&r).unwrap(), big);
        assert_eq!(Repo::blob_ref(&big), r);
    }

    #[test]
    fn clone_push_pull_with_seals_and_attestations() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let origin_path = root.join("origin");
        let origin = Repo::init(&origin_path).unwrap();
        let origin_url = origin_path.to_string_lossy().to_string();

        // A clones, creates an identity (default core.sign = seal), commits, pushes.
        let mut a = Repo::clone(&origin_url, &root.join("a")).unwrap().with_keys_dir(root.join("keys-a"));
        assert_eq!(a.id().unwrap(), origin.id().unwrap());
        let (key_a, _) = a.create_identity("Ada", "[email protected]").unwrap();
        write(&root.join("a"), "f.txt", b"a\n");
        let h1 = a.commit("first", &[]).unwrap();
        let results = a.push("origin", false).unwrap();
        assert!(results[0].ok, "{}", results[0].reason);
        assert_eq!(origin.bookmark_heads().unwrap(), vec![h1]);
        // The change was sealed at push and the reference attested.
        assert!(matches!(origin.authenticate_change(&h1).unwrap(), SignatureStatus::Valid { key, sealed: true, .. } if key == key_a));
        assert_eq!(origin.verify_change(&h1).unwrap(), SignatureStatus::Unsigned);
        let (_, att) = origin.latest_ref_attest("main").unwrap().unwrap();
        assert!(matches!(att.attest.body, AttestBody::Ref { serial: 1, .. }));
        let again = a.push("origin", false).unwrap();
        assert!(again[0].ok && again[0].reason.contains("up to date"));
        let (_, att) = origin.latest_ref_attest("main").unwrap().unwrap();
        assert!(matches!(att.attest.body, AttestBody::Ref { serial: 1, .. }), "a no-op push does not attest again");

        // B clones and sees the file and the seal.
        let b = Repo::clone(&origin_url, &root.join("b")).unwrap();
        assert_eq!(fs::read(root.join("b/f.txt")).unwrap(), b"a\n");
        assert_eq!(b.bookmark_heads().unwrap(), vec![h1]);
        assert!(matches!(b.authenticate_change(&h1).unwrap(), SignatureStatus::Valid { sealed: true, .. }));

        // B (no identity) commits and pushes unsigned; the unverified origin accepts.
        write(&root.join("b"), "f.txt", b"a\nb\n");
        let h2 = b.commit("second", &[]).unwrap();
        assert!(b.push("origin", false).unwrap()[0].ok);
        assert_eq!(origin.bookmark_heads().unwrap(), vec![h2]);

        // A commits an independent change; push is refused until A pulls.
        write(&root.join("a"), "g.txt", b"g\n");
        let h3 = a.commit("third", &[]).unwrap();
        assert!(a.push("origin", false).is_err());
        let pr = a.pull("origin").unwrap();
        assert!(pr.changed && pr.checked_out);
        let mut want = vec![h2, h3];
        want.sort();
        assert_eq!(pr.heads, want);
        assert_eq!(fs::read(root.join("a/f.txt")).unwrap(), b"a\nb\n");
        assert_eq!(fs::read(root.join("a/g.txt")).unwrap(), b"g\n");
        let results = a.push("origin", false).unwrap();
        assert!(results[0].ok, "{}", results[0].reason);
        let mut origin_heads = origin.bookmark_heads().unwrap();
        origin_heads.sort();
        assert_eq!(origin_heads, want);
        let (_, att) = origin.latest_ref_attest("main").unwrap().unwrap();
        assert!(matches!(att.attest.body, AttestBody::Ref { serial: 2, .. }));

        // B pulls and ends up identical.
        let pr = b.pull("origin").unwrap();
        assert_eq!(pr.heads, want);
        assert_eq!(fs::read(root.join("b/g.txt")).unwrap(), b"g\n");
        assert!(!b.snapshot("status").unwrap().changed);

        // Concurrent edits of the same line: the union is a reified conflict.
        write(&root.join("a"), "f.txt", b"a\nA\n");
        a.commit("a-edit", &[]).unwrap();
        a.push("origin", false).unwrap();
        write(&root.join("b"), "f.txt", b"a\nB\n");
        b.commit("b-edit", &[]).unwrap();
        let pr = b.pull("origin").unwrap();
        assert!(pr.changed && pr.checked_out);
        let text = fs::read_to_string(root.join("b/f.txt")).unwrap();
        assert!(text.contains("<<<<<<< oxy conflict"), "{text}");
        write(&root.join("b"), "f.txt", b"a\nAB\n");
        let hr = b.commit("resolve", &[]).unwrap();
        assert_eq!(b.store().get_change(&hr).unwrap().kind, ChangeKind::Resolution);
        assert!(b.push("origin", false).unwrap()[0].ok);
        a.pull("origin").unwrap();
        assert_eq!(fs::read(root.join("a/f.txt")).unwrap(), b"a\nAB\n");
        assert_eq!(a.bookmark_heads().unwrap(), vec![hr]);
    }

    #[test]
    fn receive_push_rejects_bad_updates() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let origin = Repo::init(&root.join("origin")).unwrap();
        let url = root.join("origin").to_string_lossy().to_string();
        let mut a = Repo::clone(&url, &root.join("a")).unwrap().with_keys_dir(root.join("keys"));
        let (key, _) = a.create_identity("Ada", "a@b", ).unwrap();
        write(&root.join("a"), "f.txt", b"x\n");
        let h1 = a.commit("one", &[]).unwrap();
        assert!(a.push("origin", false).unwrap()[0].ok);
        let empty = origin.store().put_state(&StateObject::new(vec![])).unwrap();
        let s1 = origin.store().put_state(&StateObject::new(vec![h1])).unwrap();

        // Missing head.
        let ghost = origin.store().put_state(&StateObject::new(vec![ObjectRef([9; 32])])).unwrap();
        let r = origin.receive_push(Bundle::default(), vec![RefUpdate { name: "main".into(), old_state: s1, new_state: ghost, force: false, attestation: None }]).unwrap();
        assert!(!r[0].ok && r[0].reason.contains("missing"), "{}", r[0].reason);

        // Stale old_state.
        let r = origin.receive_push(Bundle::default(), vec![RefUpdate { name: "main".into(), old_state: empty, new_state: s1, force: false, attestation: None }]).unwrap();
        assert!(!r[0].ok && r[0].reason.contains("stale"), "{}", r[0].reason);

        // Non-fast-forward without force is refused; with force it passes.
        let r = origin.receive_push(Bundle::default(), vec![RefUpdate { name: "main".into(), old_state: s1, new_state: empty, force: false, attestation: None }]).unwrap();
        assert!(!r[0].ok && r[0].reason.contains("fast-forward"), "{}", r[0].reason);
        let r = origin.receive_push(Bundle::default(), vec![RefUpdate { name: "main".into(), old_state: s1, new_state: empty, force: true, attestation: None }]).unwrap();
        assert!(r[0].ok);
        assert_eq!(origin.bookmark_heads().unwrap(), vec![]);

        // Attestation with a stale serial is a rollback and is refused.
        let sa = a.sign_attest(&Attest { repo: a.id().unwrap(), hlc: Hlc::now(), body: AttestBody::Ref { name: "main".into(), old_state: empty, new_state: s1, serial: 1 } }).unwrap();
        let r = origin.receive_push(Bundle::default(), vec![RefUpdate { name: "main".into(), old_state: empty, new_state: s1, force: false, attestation: Some(sa.clone()) }]).unwrap();
        assert!(!r[0].ok && r[0].reason.contains("serial"), "{}", r[0].reason);
        // An attestation for a different update is refused too.
        let sa2 = a.sign_attest(&Attest { repo: a.id().unwrap(), hlc: Hlc::now(), body: AttestBody::Ref { name: "main".into(), old_state: s1, new_state: empty, serial: 5 } }).unwrap();
        let r = origin.receive_push(Bundle::default(), vec![RefUpdate { name: "main".into(), old_state: empty, new_state: s1, force: false, attestation: Some(sa2) }]).unwrap();
        assert!(!r[0].ok && r[0].reason.contains("describe"), "{}", r[0].reason);
        let _ = key;
    }

    #[test]
    fn format1_repositories_are_migrated_on_open() {
        use crate::oplog::{Format1Op, Format1View};
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let repo = Repo::init(root).unwrap();
        write(root, "a.txt", b"a\n");
        let h1 = repo.commit("one", &[]).unwrap();
        let (wc_hash, _) = repo.working_copy().unwrap();
        // Rewrite the op log the way format 1 stored it: two ops, head lists.
        let mut v1 = Format1View::default();
        v1.bookmarks.insert("main".into(), vec![]);
        v1.workspaces.insert(repo.workspace(), wc_hash);
        let init = Format1Op { parents: vec![], hlc: Hlc::default(), command: "oxy init".into(), view: v1.clone() };
        let init_ref = repo.store().put(ObjectType::Op, &init.encode()).unwrap();
        v1.bookmarks.insert("main".into(), vec![h1]);
        let commit = Format1Op { parents: vec![init_ref], hlc: Hlc::default(), command: "oxy commit".into(), view: v1 };
        let commit_ref = repo.store().put(ObjectType::Op, &commit.encode()).unwrap();
        write_atomic(&root.join(".oxy/ops/head"), commit_ref.to_hex().as_bytes()).unwrap();
        write_atomic(&root.join(".oxy/format"), FORMAT1_LINE.as_bytes()).unwrap();
        drop(repo);

        let repo = Repo::open(root).unwrap();
        assert_eq!(fs::read_to_string(root.join(".oxy/format")).unwrap(), FORMAT_LINE);
        assert_eq!(repo.bookmark_heads().unwrap(), vec![h1]);
        let ops = repo.op_log().unwrap();
        assert_eq!(ops.iter().map(|(_, o)| o.command.as_str()).collect::<Vec<_>>(), ["oxy commit", "oxy init"]);
        assert_eq!(repo.heads_of(&ops[1].1.view, "main").unwrap(), vec![]);
        assert!(!repo.snapshot("status").unwrap().changed);
        // Reopening again is a no-op.
        assert_eq!(Repo::open(root).unwrap().op_log().unwrap().len(), 2);
    }

    #[test]
    fn undo_skips_snapshot_operations() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let repo = Repo::init(root).unwrap();
        write(root, "a.txt", b"a\n");
        let h1 = repo.commit("a", &[]).unwrap();
        // A later command snapshots new edits on top of the commit.
        write(root, "b.txt", b"b\n");
        let s = repo.snapshot("oxy status").unwrap();
        assert!(s.changed);
        assert!(repo.head_op().unwrap().1.is_snapshot());
        assert_eq!(repo.last_command().unwrap().command, "oxy commit -m \"a\"");
        // Undo must undo the commit, not the snapshot.
        repo.undo().unwrap();
        assert_eq!(repo.bookmark_heads().unwrap(), vec![]);
        let s = repo.snapshot("oxy status").unwrap();
        let paths: Vec<_> = s.statuses.iter().map(|p| p.path.as_str()).collect();
        assert_eq!(paths, ["a.txt", "b.txt"], "both files are back in the working copy");
        assert!(repo.store().get_change(&h1).unwrap().deps.is_empty());
        // Only snapshots remain above `init`, so there is nothing left to undo.
        assert_eq!(repo.last_command().unwrap().command, "oxy init");
        assert!(repo.undo().is_err());
    }

    #[test]
    fn independent_changes_commute_and_make_multiple_heads() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let repo = Repo::init(root).unwrap();
        write(root, "a.txt", b"a\n");
        let h1 = repo.commit("a", &[]).unwrap();
        write(root, "b.txt", b"b\n");
        let h2 = repo.commit("b", &[]).unwrap();
        let c2 = repo.store().get_change(&h2).unwrap();
        assert!(c2.deps.is_empty(), "b.txt touches nothing from h1");
        let mut heads = repo.bookmark_heads().unwrap();
        heads.sort();
        let mut want = vec![h1, h2];
        want.sort();
        assert_eq!(heads, want);
        // Editing a.txt depends on h1 only.
        write(root, "a.txt", b"a\na2\n");
        let h3 = repo.commit("a2", &[]).unwrap();
        assert_eq!(repo.store().get_change(&h3).unwrap().deps, vec![h1]);
        let heads: BTreeSet<_> = repo.bookmark_heads().unwrap().into_iter().collect();
        assert_eq!(heads, [h2, h3].into_iter().collect());
        // Explicit dependency.
        write(root, "c.txt", b"c\n");
        let h4 = repo.commit("c", &[h2]).unwrap();
        assert_eq!(repo.store().get_change(&h4).unwrap().deps, vec![h2]);
    }

    #[test]
    fn mode_change_and_text_binary_switch() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        let repo = Repo::init(root).unwrap();
        write(root, "run.sh", b"#!/bin/sh\n");
        repo.commit("add script", &[]).unwrap();
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            fs::set_permissions(root.join("run.sh"), fs::Permissions::from_mode(0o755)).unwrap();
            let s = repo.snapshot("status").unwrap();
            assert_eq!(statuses(&s), vec![("run.sh".into(), ChangeStatus::ModeChanged)]);
            let h = repo.commit("exec", &[]).unwrap();
            let snap = repo.load_state(&[h]).unwrap().materialize();
            assert!(snap.files["run.sh"].mode.exec);
        }
        // Text → binary → text.
        write(root, "run.sh", b"\0binary");
        let h = repo.commit("binary", &[]).unwrap();
        let snap = repo.load_state(&[h]).unwrap().materialize();
        assert!(snap.files["run.sh"].mode.opaque);
        write(root, "run.sh", b"text again\n");
        let h = repo.commit("text", &[]).unwrap();
        let snap = repo.load_state(&[h]).unwrap().materialize();
        assert!(!snap.files["run.sh"].mode.opaque);
        assert!(matches!(&snap.files["run.sh"].content, FileContent::Text { bytes, .. } if bytes == b"text again\n"));
        assert!(!snap.is_conflicted());
    }
}
`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet
Keyboard
