Shallow clone: clone --depth, checkpoint and shallow endpoints, boundary-aware import and negotiation, oxy deepen; log from state metadata (spec 0.6g) 2863456a0f6d

    /// A checkpoint of exactly `heads` (spec §16.1 `checkpoint`): the

    /// checkpoint object, its payload blob, and the blob's chunks.

    fn checkpoint(&self, heads: &[ChangeHash]) -> Result<Bundle>;

    /// The changes within `depth` dependency steps of `heads` (spec §17).

    fn shallow(&self, heads: &[ChangeHash], depth: u32) -> Result<Vec<ChangeHash>>;

    fn checkpoint(&self, heads: &[ChangeHash]) -> Result<Bundle> {

        self.repo.checkpoint_bundle_for(heads)

    }

    fn shallow(&self, heads: &[ChangeHash], depth: u32) -> Result<Vec<ChangeHash>> {

        self.repo.shallow_changes(heads, depth)

    }

    fn checkpoint(&self, heads: &[ChangeHash]) -> Result<Bundle> {

        wire::decode_bundle(&self.call(true, "checkpoint", Some(&wire::encode_hashes(heads)))?)

    }

    fn shallow(&self, heads: &[ChangeHash], depth: u32) -> Result<Vec<ChangeHash>> {

        wire::decode_hashes(&self.call(true, "shallow", Some(&wire::encode_shallow(heads, depth)))?)

    }

    /// `shallow` request: `{0: [heads], 1: depth}`.

    pub fn encode_shallow(hs: &[ChangeHash], depth: u32) -> Vec<u8> {

        cbor::encode(&Value::map([(0, hashes_value(hs)), (1, Value::Uint(depth as u64))]))

    }

    pub fn decode_shallow(bytes: &[u8]) -> Result<(Vec<ChangeHash>, u32)> {

        let v = cbor::decode(bytes).map_err(ObjectError::from)?;

        let m = map(&v, "shallow")?;

        Ok((hashes_from(field(m, 0, "heads")?)?, o::u32_(field(m, 1, "depth")?, "depth")?))

    }

        assert_eq!(wire::decode_shallow(&wire::encode_shallow(&[c.hash()], 3)).unwrap(), (vec![c.hash()], 3));

    /// Point `bookmark` at an already stored checkpoint (a shallow clone's base).

    pub(crate) fn install_checkpoint(&self, bookmark: &str, r: &ObjectRef) -> Result<()> {

        Checkpoint::decode(&self.store.get_typed(r, ObjectType::Checkpoint)?)?;

        fs::create_dir_all(self.oxy.join("checkpoints"))?;

        write_atomic(&self.checkpoint_pointer(bookmark), r.to_hex().as_bytes())

    }

    /// A bundle holding a checkpoint of exactly `heads` with its payload

    /// (spec §16.1 `checkpoint`); the current bookmark checkpoint is reused

    /// when it matches, otherwise one is made and, when `heads` are the

    /// bookmark's, kept.

    pub fn checkpoint_bundle_for(&self, heads: &[ChangeHash]) -> Result<Bundle> {

        let wanted = StateObject::new(heads.to_vec()).heads;

        let bookmark = self.config.bookmark.clone();

        let current = self.bookmark_heads()?;

        let r = match self.latest_checkpoint(&bookmark)? {

            Some((r, cp)) if cp.heads == wanted => r,

            _ => {

                let state = self.load_state(&wanted)?;

                if current == wanted {

                    self.write_checkpoint(&bookmark, &state, &wanted)?.0

                } else {

                    let payload = state.checkpoint_payload();

                    let blob = self.store_blob(&payload)?;

                    let cp = Checkpoint { heads: wanted.clone(), count: state.len() as u64, payload: blob };

                    self.store.put(ObjectType::Checkpoint, &cp.encode())?

                }

            }

        };

        let cp = Checkpoint::decode(&self.store.get_typed(&r, ObjectType::Checkpoint)?)?;

        let mut bundle = Bundle::default();

        for c in Blob::decode(&self.store.get_typed(&cp.payload, ObjectType::Blob)?)?.chunks {

            bundle.objects.push(self.store.get(&c)?);

        }

        bundle.objects.push(self.store.get(&cp.payload)?);

        bundle.objects.push((ObjectType::Checkpoint, cp.encode()));

        Ok(bundle)

    }

            // Beyond the shallow boundary there is nothing to keep.

            let c = match self.store.get_change(&h) {

                Ok(c) => c,

                Err(StoreError::NotFound(_)) => continue,

                Err(e) => return Err(e.into()),

            };

    /// Metadata from the state; the full change may be absent in a shallow repository.

    pub change: crate::state::ChangeMeta,

        for (h, meta) in state.changes() {

            entries.push(LogEntry { hash: *h, change: meta.clone(), is_working_copy: *h == wc_hash, is_head: head_set.contains(h) });

    /// The changes within `depth` dependency steps of `heads` (spec §17),

    /// nearest first; depth 1 is the heads themselves.

    pub fn shallow_changes(&self, heads: &[ChangeHash], depth: u32) -> Result<Vec<ChangeHash>> {

        let mut out = Vec::new();

        let mut seen: BTreeSet<ChangeHash> = BTreeSet::new();

        let mut layer: Vec<ChangeHash> = heads.to_vec();

        for _ in 0..depth.max(1) {

            let mut next = Vec::new();

            for h in layer {

                if !seen.insert(h) || !self.store.has(&h) {

                    continue;

                }

                let c = self.store.get_change(&h)?;

                next.extend(c.deps.iter().copied());

                out.push(h);

            }

            if next.is_empty() {

                break;

            }

            layer = next;

        }

        out.reverse();

        Ok(out)

    }

    fn shallow_path(&self) -> PathBuf {

        self.oxy.join("shallow")

    }

    /// The shallow boundary: dependencies this repository does not hold (spec §17).

    pub fn boundary(&self) -> BTreeSet<ChangeHash> {

        fs::read_to_string(self.shallow_path()).map(|t| t.lines().filter_map(ObjectRef::from_hex).collect()).unwrap_or_default()

    }

    pub fn is_shallow(&self) -> bool {

        !self.boundary().is_empty()

    }

    fn write_boundary(&self, boundary: &BTreeSet<ChangeHash>) -> Result<()> {

        if boundary.is_empty() {

            let _ = fs::remove_file(self.shallow_path());

            return Ok(());

        }

        let text: String = boundary.iter().map(|h| format!("{}\n", h.to_hex())).collect();

        write_atomic(&self.shallow_path(), text.as_bytes())

    }

    /// Recompute the boundary from what is stored: every dependency of a

    /// stored change that is not itself stored.

    fn refresh_boundary(&self, imported: &[ChangeHash]) -> Result<()> {

        let mut boundary = self.boundary();

        boundary.retain(|h| !self.store.has(h));

        for h in imported {

            for d in self.store.get_change(h)?.deps {

                if !self.store.has(&d) {

                    boundary.insert(d);

                }

            }

        }

        self.write_boundary(&boundary)

    }

    /// Fetch `depth` more levels of history below the shallow boundary.

    pub fn deepen(&self, remote_name: &str, depth: u32) -> Result<usize> {

        let boundary = self.boundary();

        if boundary.is_empty() {

            return Ok(0);

        }

        let remote = self.open_named_remote(remote_name)?;

        let wanted = remote.shallow(&boundary.iter().copied().collect::<Vec<_>>(), depth)?;

        let bundle = remote.fetch(&wanted, self.config.max_blob)?;

        let imported = self.import_bundle_shallow(&bundle, false)?;

        if self.config.max_blob.is_some() {

            self.register_missing_blobs(&imported, remote_name)?;

        }

        self.refresh_boundary(&imported)?;

        Ok(imported.len())

    }

        // In a shallow repository the walk stops at the boundary, whose

        // changes the remote is assumed to hold.

        let boundary = self.boundary();

        done.extend(boundary.iter().copied());

        self.import_bundle_inner(bundle, strict, false)

    }

    /// Like `import_bundle`, accepting changes whose dependencies are absent

    /// (they join the shallow boundary).

    pub fn import_bundle_shallow(&self, bundle: &Bundle, strict: bool) -> Result<Vec<ChangeHash>> {

        self.import_bundle_inner(bundle, strict, true)

    }

    fn import_bundle_inner(&self, bundle: &Bundle, strict: bool, shallow: bool) -> Result<Vec<ChangeHash>> {

                ObjectType::Chunk | ObjectType::Blob | ObjectType::Identity | ObjectType::State | ObjectType::Checkpoint => {

        let boundary = self.boundary();

                if !self.store.has(d) && !incoming.contains(d) && !shallow && !boundary.contains(d) {

    /// Shallow fetch of the remote's bookmark: its checkpoint as our base,

    /// the changes within `depth` steps of its heads, and the boundary below.

    pub fn fetch_shallow(&self, remote_name: &str, depth: u32) -> Result<usize> {

        let remote = self.open_named_remote(remote_name)?;

        if remote.repo_id()? != self.id()? {

            return fail(format!("remote {remote_name:?} is a different repository (repository IDs differ)"));

        }

        let resp = remote.refs()?;

        let bookmark = self.config.bookmark.clone();

        if let Some(sp) = &resp.policy {

            let local = self.current_policy()?.map(|(_, sp)| sp.policy);

            self.check_policy(sp, local.as_ref()).map_err(|e| RepoError::Msg(format!("policy from {remote_name}: {e}")))?;

            self.set_policy(sp, &format!("oxy clone --depth (policy serial {})", sp.policy.serial))?;

            self.record_policy_serial(remote_name, sp.policy.serial)?;

        }

        let Some(r) = resp.refs.into_iter().find(|r| r.name == bookmark) else {

            return fail(format!("{remote_name} has no bookmark {bookmark:?}"));

        };

        if r.heads.is_empty() {

            return Ok(0);

        }

        // Base: the remote's checkpoint of exactly these heads.

        let cp_bundle = remote.checkpoint(&r.heads)?;

        let mut cp_ref = None;

        for (ty, body) in &cp_bundle.objects {

            let put = self.store.put(*ty, body)?;

            if *ty == ObjectType::Checkpoint {

                cp_ref = Some(put);

            }

        }

        let Some(cp_ref) = cp_ref else { return fail(format!("{remote_name} sent no checkpoint")) };

        self.install_checkpoint(&bookmark, &cp_ref)?;

        // History window.

        let wanted = remote.shallow(&r.heads, depth)?;

        let bundle = remote.fetch(&wanted, self.config.max_blob)?;

        let imported = self.import_bundle_shallow(&bundle, false)?;

        if self.config.max_blob.is_some() {

            self.register_missing_blobs(&imported, remote_name)?;

        }

        self.refresh_boundary(&imported)?;

        if let Some(sa) = &r.attestation {

            let ar = self.store.put_attest(&sa.attest)?;

            for sig in &sa.sigs {

                self.store.put_signature(&ar, sig)?;

            }

            if let AttestBody::Ref { serial, .. } = sa.attest.body {

                self.record_serial(remote_name, &r.name, serial)?;

            }

        }

        let state = self.store.put_state(&StateObject::new(r.heads.clone()))?;

        let (op_ref, op) = self.head_op()?;

        let mut view = op.view.clone();

        view.remotes.entry(remote_name.to_string()).or_default().insert(r.name.clone(), state);

        self.record_op(&[op_ref], &format!("oxy fetch {remote_name} --depth {depth}"), view)?;

        Ok(imported.len())

    }

        Self::clone_full(url, dest, max_blob, sparse, None)

    }

    /// Shallow clone (spec §17): a checkpoint of the bookmark's heads plus the

    /// changes within `depth` steps of them; the rest is the boundary.

    pub fn clone_shallow(url: &str, dest: &Path, depth: u32, max_blob: Option<u64>, sparse: &[String]) -> Result<Repo> {

        Self::clone_full(url, dest, max_blob, sparse, Some(depth))

    }

    fn clone_full(url: &str, dest: &Path, max_blob: Option<u64>, sparse: &[String], depth: Option<u32>) -> Result<Repo> {

        if let Some(depth) = depth {

            repo.fetch_shallow("origin", depth)?;

        } else {

            repo.fetch("origin")?;

        }

#[test]

fn shallow_clone_and_deepen() {

    hermetic();

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

    let root = dir.path();

    let origin_dir = root.join("origin");

    let origin = Repo::init(&origin_dir).unwrap().with_home(root.join("home"));

    let mut hashes = Vec::new();

    for i in 0..8 {

        write(&origin_dir, "a.txt", format!("{}\n", (0..=i).map(|k| k.to_string()).collect::<Vec<_>>().join("\n")).as_bytes());

        hashes.push(origin.commit(&format!("c{i}"), &[]).unwrap());

    }

    let url = origin_dir.to_string_lossy().to_string();

    let a = Repo::clone_shallow(&url, &root.join("a"), 3, None, &[]).unwrap().with_home(root.join("home"));

    assert!(a.is_shallow());

    assert_eq!(fs::read_to_string(root.join("a/a.txt")).unwrap(), "0\n1\n2\n3\n4\n5\n6\n7\n");

    assert!(a.store().has(&hashes[7]) && a.store().has(&hashes[5]), "three levels present");

    assert!(!a.store().has(&hashes[4]), "beyond the depth is absent");

    assert_eq!(a.boundary(), [hashes[4]].into_iter().collect());

    assert_eq!(a.log().unwrap().len(), 9, "the log shows every change from the checkpoint's metadata");

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

    assert_eq!(a.quick_status().unwrap().heads, 1);

    // Work continues on top of the shallow history and pushes back.

    write(&root.join("a"), "a.txt", b"0\n1\n2\n3\n4\n5\n6\n7\n8\n");

    let h_new = a.commit("c8", &[]).unwrap();

    assert!(a.push("origin", false).unwrap()[0].ok);

    assert_eq!(origin.bookmark_heads().unwrap(), vec![h_new]);

    // Fetching new work from origin into the shallow clone works too.

    write(&origin_dir, "b.txt", b"b\n");

    origin.pull("origin").err();

    let (_, wc) = origin.working_copy().unwrap();

    let _ = wc;

    origin.checkout(&origin.bookmark_heads().unwrap(), true, "co").unwrap();

    write(&origin_dir, "b.txt", b"b\n");

    let h_b = origin.commit("b", &[]).unwrap();

    let pr = a.pull("origin").unwrap();

    assert!(pr.changed);

    assert!(a.store().has(&h_b));

    assert!(root.join("a/b.txt").exists());

    // Deepening fetches older history until the boundary is gone.

    // Every commit also depends on the change that created the file, so two

    // levels below the boundary hold h4, h3, and the root.

    assert!(a.deepen("origin", 2).unwrap() >= 2);

    assert!(a.store().has(&hashes[3]));

    assert!(a.is_shallow());

    a.deepen("origin", 100).unwrap();

    assert!(!a.is_shallow(), "boundary reached the root");

    assert!(a.store().has(&hashes[0]));

    assert_eq!(a.load_state_full(&a.bookmark_heads().unwrap()).unwrap().len(), 10);

}

async fn checkpoint(State(app): State<Shared>, Path(repo): Path<String>, body: Bytes) -> Result<Response, Failure> {

    blocking(move || {

        let r = app.open(&repo)?;

        let heads = wire::decode_hashes(&body)?;

        let lock = app.lock_for(&repo);

        let _guard = lock.lock().unwrap();

        Ok(ok(wire::encode_bundle(&r.checkpoint_bundle_for(&heads)?)))

    })

    .await

}

async fn shallow(State(app): State<Shared>, Path(repo): Path<String>, body: Bytes) -> Result<Response, Failure> {

    blocking(move || {

        let r = app.open(&repo)?;

        let (heads, depth) = wire::decode_shallow(&body)?;

        Ok(ok(wire::encode_hashes(&r.shallow_changes(&heads, depth)?)))

    })

    .await

}

        .route("/{repo}/oxy/v1/checkpoint", post(checkpoint))

        .route("/{repo}/oxy/v1/shallow", post(shallow))

| **Status** | Draft 0.6g |

| `checkpoint` request | `{0: [heads]}`; response a `Bundle` of objects: the checkpoint of exactly those heads, its payload blob, and the blob's chunks |

| `shallow` request | `{0: [heads], 1: depth}`; response `{0: [hashes]}`, the changes within `depth` steps of the heads, dependencies first |

The HTTP content type is `application/oxy-cbor`.

- **Shallow** repositories hold a checkpoint of their bookmark's heads (obtained with the `checkpoint` message) and the changes within `depth` dependency steps of those heads (the `shallow` message lists them). The *shallow boundary* is the set of dependencies of stored changes that are not stored (`.oxy/shallow`). Dependencies into the boundary are accepted as well-formed, negotiation stops at the boundary (the remote is assumed to hold it), and the log shows every change from the checkpoint's metadata. `oxy deepen N` fetches `N` more levels below the boundary; when nothing remains the repository is no longer shallow.

*Changelog.* Draft 0.6g (2026-09-27): shallow repositories as checkpoint plus history window, the `checkpoint` and `shallow` messages, deepening (§16.3, §17).

Draft 0.6f (2026-09-27): sparse checkout semantics (§17).

use oxy_core::state::ChangeMeta;

pub fn short_meta_id(c: &ChangeMeta) -> String {

    c.change_id.short(8)

}

    deps_of(&c.deps)

}

pub fn deps_of(deps: &[oxy_core::hash::ChangeHash]) -> String {

    deps.iter().map(|d| format!("#{}", d.short(12))).collect::<Vec<_>>().join(" ")

        let Ok(c) = repo.store().get_change(&h) else {

            println!("{}  {}", ui::hash(format!("#{}", h.short(12))), ui::dim("not present (shallow)"));

            continue;

        };

        /// Shallow clone: fetch only this many levels of history below the heads

        #[arg(long)]

        depth: Option<u32>,

    /// Fetch more history below a shallow clone's boundary

    Deepen {

        #[arg(default_value_t = 10)]

        depth: u32,

        #[arg(long, default_value = "origin")]

        remote: String,

    },

        Cmd::Clone { url, dest, max_blob, sparse, depth } => sync::clone(&url, dest, max_blob.as_deref(), &sparse, depth),

        Cmd::Deepen { depth, remote } => sync::deepen(&remote, depth),

pub fn clone(url: &str, dest: Option<PathBuf>, max_blob: Option<&str>, sparse: &[String], depth: Option<u32>) -> Result<i32> {

    let repo = match depth {

        Some(d) => Repo::clone_shallow(url, &dest, d, max_blob, sparse)?,

        None => Repo::clone_with(url, &dest, max_blob, sparse)?,

    };

pub fn deepen(remote: &str, depth: u32) -> Result<i32> {

    let repo = open()?;

    if !repo.is_shallow() {

        println!("{}", ui::dim("This repository is not shallow; nothing to deepen."));

        return Ok(0);

    }

    let sp = ui::spinner(&format!("Fetching {depth} more levels from {remote}…"));

    let n = repo.deepen(remote, depth)?;

    sp.done(&format!("{} {}; {}", ui::ok("Deepened by"), plural(n, "change"), if repo.is_shallow() { "still shallow".to_string() } else { ui::ok("history is now complete") }));

    Ok(0)

}

use super::format::{deps_line, deps_of, plural, short_id, short_meta_id, signature_line, when};

        println!("{} {}{}", ui::id(short_meta_id(c)), ui::hash(format!("#{}", e.hash.short(12))), flags);

            println!("    {}", ui::dim(format!("deps: {}", deps_of(&c.deps))));