Never move a subrepo's bookmark backwards from its parent 1a3b62032ed9

        // A subrepo whose pin is carried work keeps its own state: checking

        // it out at the target's pin would roll it back (oxygen#38).

        let keep: BTreeSet<String> = touched

            .iter()

            .filter(|p| {

                snap.base_snapshot

                    .files

                    .get(*p)

                    .or_else(|| target_state.files.get(*p))

                    .is_some_and(|f| f.kind == NodeKind::Subrepo)

            })

            .cloned()

            .collect();

            if keep.contains(p) {

                carried.push((p.clone(), Carried::Subrepo));

                continue;

            }

        let report = self.checkout_keeping(heads, true, command, &keep)?;

                Carried::Subrepo => {}

    /// A subrepo whose pin is carried: left as it is.

    Subrepo,

        self.checkout_keeping(heads, discard, command, &BTreeSet::new())

    }

    /// [`Repo::checkout`], leaving the nested repositories at

    /// `keep_subrepos` as they are (their pins are carried work).

    pub(crate) fn checkout_keeping(

        &self,

        heads: &[ChangeHash],

        discard: bool,

        command: &str,

        keep_subrepos: &BTreeSet<String>,

    ) -> Result<CheckoutReport> {

                        if keep_subrepos.contains(path) {

                            continue;

                        }

                        let sync = self.sync_subrepo(path, &pin, false)?;

                        if matches!(

                            sync,

                            SubrepoSync::Updated | SubrepoSync::KeptBookmark { .. }

                        ) {

                            report.written += 1;

                        report.notes.extend(sync.note(path));

    /// The working copy was brought to the pin, but the nested repository's

    /// bookmark has changes the pin lacks, so it was left where it is: a

    /// bookmark is never moved backwards (spec §7.8).

    KeptBookmark {

        bookmark: String,

        newer: usize,

    },

impl SubrepoSync {

    /// A note for a checkout report, when there is something to say.

    pub fn note(&self, path: &str) -> Option<String> {

        match self {

            SubrepoSync::Updated | SubrepoSync::UpToDate => None,

            SubrepoSync::Missing => Some(format!(

                "{path}: nested repository not present; run oxy submodule update --init"

            )),

            SubrepoSync::Dirty => Some(format!(

                "{path}: nested repository has uncommitted changes; left as is"

            )),

            SubrepoSync::KeptBookmark { bookmark, newer } => Some(format!(

                "{path}: checked out at the pin; its bookmark {bookmark} keeps {newer} newer change{} (oxy bookmark switch {bookmark} there to return to them)",

                if *newer == 1 { "" } else { "s" }

            )),

            SubrepoSync::Failed(e) => Some(format!("{path}: {e}")),

        }

    }

}

/// The pin a nested repository at `dir` is at: the base of its working

/// copy for an Oxygen repository (which is its bookmark's heads unless a

/// parent checked out an older pin), `HEAD` for a Git one.

            heads: nested.working_copy()?.1.deps,

                        // Its bookmark follows only forward: work it has

                        // beyond the pin stays on it (metalgear, oxygen#38).

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

                        let at = nested.bookmark_heads().unwrap_or_default();

                        let newer = nested.state_gap(&at, heads).map(|g| g.lacks).unwrap_or(0);

                        if newer == 0 {

                            let _ = nested.bookmark_set(&bookmark, heads);

                            Ok(SubrepoSync::Updated)

                        } else {

                            Ok(SubrepoSync::KeptBookmark { bookmark, newer })

                        }

    // Checking out the older app state brings the nested working copy back

    // to the older pin, but never moves its bookmark backwards (oxygen#38).

    assert!(

        r.notes.len() == 1 && r.notes[0].contains("keeps 1 newer change"),

        "{:?}",

        r.notes

    );

    let nested = Repo::open(&app_dir.join("libs/lib")).unwrap();

    assert_eq!(nested.bookmark_heads().unwrap(), vec![l2]);

    assert_eq!(nested.working_copy().unwrap().1.deps, vec![l1]);

}

/// Metalgear, 2026-09-29 (oxygen#38): a parent's `bookmark switch --carry`

/// put a subrepo that was ahead of its pin back at the pin and moved the

/// subrepo's own bookmark backwards.

#[test]

fn a_parent_switch_with_carry_leaves_a_subrepo_ahead_of_its_pin_alone() {

    hermetic();

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

    let root = dir.path();

    Repo::init(&root.join("lib-origin")).unwrap();

    let lib_url = root.join("lib-origin").to_string_lossy().to_string();

    let lib = Repo::clone(&lib_url, &root.join("lib")).unwrap();

    write(&root.join("lib"), "lib.txt", b"v1\n");

    lib.commit("lib v1", &[]).unwrap();

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

    let app_dir = root.join("app");

    let mut app = Repo::init(&app_dir).unwrap();

    write(&app_dir, "main.txt", b"app\n");

    app.submodule_add(&lib_url, "libs/lib", None).unwrap();

    app.commit("app with lib", &[]).unwrap();

    app.bookmark_create("feature", None).unwrap();

    // New work in the subrepo, not yet pinned by the parent.

    let nested_dir = app_dir.join("libs/lib");

    let nested = Repo::open(&nested_dir).unwrap();

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

    let l2 = nested.commit("lib: new file", &[]).unwrap();

    drop(nested);

    let (_, carried) = app.bookmark_switch_carry("feature").unwrap();

    assert!(carried.contains(&"libs/lib".to_string()), "{carried:?}");

    let nested = Repo::open(&nested_dir).unwrap();

    assert!(

        nested.bookmark_heads().unwrap().contains(&l2),

        "its bookmark kept its work"

    );

    assert!(nested_dir.join("new.txt").exists(), "and its files");

    let s = app.snapshot("status").unwrap();

    assert_eq!(

        statuses(&s),

        vec![("libs/lib".to_string(), ChangeStatus::Modified)]

    );

In the working copy a subrepo is a directory holding its own `.oxy/` (or `.git/`). The snapshot MUST NOT descend into it; it reads the base of the nested repository's working copy (its bookmark's heads unless a parent checked out an older pin; or Git `HEAD`) as the pin, so committing the parent records whatever the nested repository is at, as in Git. A nested repository that is neither registered in `.oxymodules` nor tracked as a subrepo node is left alone entirely: not walked, not added. A tracked subrepo whose directory is absent keeps its recorded pin, as a Git gitlink does. `oxy checkout` of the parent MUST move an existing nested repository to the pinned state (`oxy checkout` of those heads, or `git checkout --detach <sha>`), fetching from the recorded remote when objects are missing. It moves the nested repository's bookmark only forward: when the bookmark has changes the pin lacks, the bookmark stays where it is and the checkout says so, as Git leaves a submodule's branch alone. A checkout that carries work (`--carry`) leaves a subrepo whose pin is part of that work as it is. It MUST leave an absent nested repository absent until `oxy submodule update --init` clones it, and MUST never delete a nested repository, even when the target state has no node for it. A nested working copy with uncommitted changes is never overwritten: the checkout reports it and continues.

*Changelog.* Draft 0.8r (2026-09-29): a parent checkout never moves a subrepo's bookmark backwards, and the pin is read from the nested working copy (§7.8); `bookmark create --upto/--only` (§10.1); the working-copy lock covers every command that writes the working copy; a workspace changed by two concurrent operations is an error (§12.1). Draft 0.8q (2026-09-29): change format version 2 stores large inserts as text blobs, so a change does not grow with the files it adds (§6.1, §7.4); no object may exceed 1 GiB (§13.2). Draft 0.8p (2026-09-29): Git import derives new NodeIds from the commit, making imports deterministic (§23). Draft 0.8o (2026-09-29): execution receipts, the `receipt` object and attestation (§14.6). Draft 0.8n (2026-09-29): line history, `oxy log -L` (§27). Draft 0.8m (2026-09-29): resolving replace conflicts (§9.3). Draft 0.8l (2026-09-28): deleting a reference on a remote; first serials from the clock (§16.4). Draft 0.8k (2026-09-28): the manifest records graph keys, so unchanged files are neither read nor rendered (§12.4). Draft 0.8j (2026-09-28): checkpoint payload version 2, file graphs by reference (§11).

            KeptBookmark { bookmark, newer } => ui::warn(format!(

                "{} checked out at the pin; its bookmark {bookmark} keeps {} the pin lacks",

                ui::glyph("⚠", "!"),

                plural(newer, "newer change")

            )),