Bookmarks point at state objects (spec 0.5, repository format 2) with migration from format 1 86e682c242c6

    State,

    pub const ALL: [ObjectType; 9] = [

        ObjectType::State,

            ObjectType::State => "state",

// ---------------------------------------------------------------- state

/// A state named by its heads (spec §10.1): what a bookmark or tag points at.

#[derive(Debug, Clone, PartialEq, Eq, Default)]

pub struct StateObject {

    pub heads: Vec<ChangeHash>,

}

impl StateObject {

    pub fn new(mut heads: Vec<ChangeHash>) -> StateObject {

        heads.sort();

        heads.dedup();

        StateObject { heads }

    }

    pub fn encode(&self) -> Vec<u8> {

        debug_assert!(self.heads.windows(2).all(|w| w[0] < w[1]));

        cbor::encode(&Value::map([

            (0, Value::Uint(FORMAT_VERSION)),

            (1, Value::Array(self.heads.iter().map(|h| Value::Bytes(h.0.to_vec())).collect())),

        ]))

    }

    pub fn hash(&self) -> ObjectRef {

        hash_object(ObjectType::State, &self.encode())

    }

    pub fn decode(bytes: &[u8]) -> Result<StateObject, ObjectError> {

        let v = cbor::decode(bytes)?;

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

        check_version(m)?;

        let heads = array(field(m, 1, "heads")?, "heads")?.iter().map(|h| oref(h, "head")).collect::<Result<Vec<_>, _>>()?;

        if !heads.windows(2).all(|w| w[0] < w[1]) {

            return schema("state heads must be sorted and unique");

        }

        Ok(StateObject { heads })

    }

}

    fn state_object_round_trip() {

        let st = StateObject::new(vec![ObjectRef([2; 32]), ObjectRef([1; 32]), ObjectRef([2; 32])]);

        assert_eq!(st.heads, vec![ObjectRef([1; 32]), ObjectRef([2; 32])]);

        assert_eq!(StateObject::decode(&st.encode()).unwrap(), st);

        assert_eq!(StateObject::new(vec![]).heads, vec![]);

        assert_ne!(StateObject::new(vec![]).hash(), st.hash());

    }

    #[test]

//! Encoding: `bookmarks` is an array of `[name, state_ref]` sorted by name and

//! canonical maps carry only integer keys. Repository format 1 encoded a

//! bookmark as `[name, [heads]]`; `Op::decode_format1` reads that for migration.

    /// Bookmark name → ObjectRef of a `state` object (spec §10.1).

    pub bookmarks: BTreeMap<String, ObjectRef>,

    pub workspaces: BTreeMap<WorkspaceId, ChangeHash>,

}

/// A format-1 view, only produced by `Op::decode_format1`.

#[derive(Clone, Debug, Default, PartialEq, Eq)]

pub struct Format1View {

                        .map(|(n, st)| Value::Array(vec![Value::Text(n.clone()), Value::Bytes(st.0.to_vec())]))

            view.bookmarks.insert(name, oref(&pair[1], "bookmark state")?);

        }

        view.workspaces = workspaces_from_value(field(m, 1, "workspaces")?)?;

        Ok(view)

    }

}

fn workspaces_from_value(v: &Value) -> Result<BTreeMap<WorkspaceId, ChangeHash>, ObjectError> {

    let mut out = BTreeMap::new();

    for w in array(v, "workspaces")? {

        let pair = array(w, "workspace")?;

        if pair.len() != 2 {

            return Err(ObjectError::Schema("workspace: expected [id, change]".into()));

        }

        let id = WorkspaceId::from_slice(bytes(&pair[0], "workspace id")?)

            .ok_or_else(|| ObjectError::Schema("workspace id: expected 16 bytes".into()))?;

        out.insert(id, oref(&pair[1], "workspace change")?);

    }

    Ok(out)

}

impl Format1View {

    fn from_value(v: &Value) -> Result<Format1View, ObjectError> {

        let m = v.as_map().ok_or_else(|| ObjectError::Schema("view: expected map".into()))?;

        let mut view = Format1View::default();

        for b in array(field(m, 0, "bookmarks")?, "bookmarks")? {

            let pair = array(b, "bookmark")?;

            if pair.len() != 2 {

                return Err(ObjectError::Schema("bookmark: expected [name, heads]".into()));

            }

            let name = text(&pair[0], "bookmark name")?.to_owned();

        view.workspaces = workspaces_from_value(field(m, 1, "workspaces")?)?;

    /// Format-1 encoding, kept for the migration test.

    #[cfg(test)]

    pub(crate) fn to_value(&self) -> Value {

        Value::map([

            (

                0,

                Value::Array(

                    self.bookmarks

                        .iter()

                        .map(|(n, hs)| {

                            Value::Array(vec![

                                Value::Text(n.clone()),

                                Value::Array(hs.iter().map(|h| Value::Bytes(h.0.to_vec())).collect()),

                            ])

                        })

                        .collect(),

                ),

            ),

            (

                1,

                Value::Array(

                    self.workspaces

                        .iter()

                        .map(|(w, h)| Value::Array(vec![Value::Bytes(w.0.to_vec()), Value::Bytes(h.0.to_vec())]))

                        .collect(),

                ),

            ),

        ])

    }

}

/// A format-1 operation as read for migration.

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Format1Op {

    pub parents: Vec<ObjectRef>,

    pub hlc: Hlc,

    pub command: String,

    pub view: Format1View,

impl Format1Op {

    #[cfg(test)]

    pub(crate) fn encode(&self) -> Vec<u8> {

        cbor::encode(&Value::map([

            (0, Value::Uint(FORMAT_VERSION)),

            (1, Value::Array(self.parents.iter().map(|p| Value::Bytes(p.0.to_vec())).collect())),

            (2, self.hlc.to_value()),

            (3, Value::Text(self.command.clone())),

            (4, self.view.to_value()),

        ]))

    }

}

    /// Read an operation written by repository format 1.

    pub fn decode_format1(b: &[u8]) -> Result<Format1Op, ObjectError> {

        let v = cbor::decode(b)?;

        let m = v.as_map().ok_or_else(|| ObjectError::Schema("op: expected map".into()))?;

        check_version(m)?;

        Ok(Format1Op {

            parents: array(field(m, 1, "parents")?, "parents")?.iter().map(|p| oref(p, "parent")).collect::<Result<Vec<_>, _>>()?,

            hlc: Hlc::from_value(field(m, 2, "hlc")?)?,

            command: text(field(m, 3, "command")?, "command")?.to_owned(),

            view: Format1View::from_value(field(m, 4, "view")?)?,

        })

    }

        view.bookmarks.insert("main".into(), ObjectRef([2; 32]));

        view.bookmarks.insert("dev".into(), ObjectRef([3; 32]));

        assert_eq!(d, op);

        // A format-1 op does not decode as format 2, but does through the migration reader.

        let mut v1 = Format1View::default();

        v1.bookmarks.insert("main".into(), vec![ObjectRef([2; 32]), ObjectRef([1; 32])]);

        v1.workspaces.insert(WorkspaceId([5; 16]), ObjectRef([9; 32]));

        let old = Format1Op { parents: vec![], hlc: Hlc::default(), command: "oxy init".into(), view: v1 };

        assert!(Op::decode(&old.encode()).is_err());

        let back = Op::decode_format1(&old.encode()).unwrap();

        assert_eq!(back.view.bookmarks["main"], vec![ObjectRef([1; 32]), ObjectRef([2; 32])]);

use crate::objects::{Blob, Change, ChangeKind, Edit, Hlc, Mode, NodeKind, OpRef, StateObject, TreeOp};

use crate::oplog::{Format1Op, Op, View, SNAPSHOT_SUFFIX};

pub const FORMAT_LINE: &str = "oxy repository format 2\n";

const FORMAT1_LINE: &str = "oxy repository format 1\n";

        view.bookmarks.insert(repo.config.bookmark.clone(), repo.store.put_state(&StateObject::new(vec![]))?);

                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);

    /// 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(())

    }

    /// 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![]),

        }

    }

        self.heads_of(&self.view()?, &self.config.bookmark)

        let old_heads = self.heads_of(&op.view, &self.config.bookmark)?;

        view.bookmarks.insert(self.config.bookmark.clone(), self.store.put_state(&StateObject::new(new_heads))?);

    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]

use crate::objects::{Change, ObjectError, StateObject};

    pub fn put_state(&self, st: &StateObject) -> Result<ObjectRef> {

        self.put(ObjectType::State, &st.encode())

    }

    pub fn get_state(&self, r: &ObjectRef) -> Result<StateObject> {

        Ok(StateObject::decode(&self.get_typed(r, ObjectType::State)?)?)

    }

| **Status** | Draft 0.5 |

| **State** | A dependency-closed set of changes. Fully determined by its maximal elements (**heads**), and named by a `state` object that lists them. |

`type-name` is one of `chunk`, `blob`, `change`, `checkpoint`, `op`, `attest`, `identity`, `policy`, `state`. The header prevents an object of one type from being presented as another. BLAKE3 with a 256-bit output retains 128-bit collision resistance against quantum attackers.

| `state` | A sorted list of heads naming a state. | §10.1 |

| `View` (in `Op`) | Key 0 bookmarks: array of `[text name, bytes(32) state ref]` sorted by name; key 1 workspaces: array of `[bytes(16) id, bytes(32) change]` sorted by id. Remote and tag namespaces are added in later drafts. Repository format 1 stored `[name, [heads]]`; format 2 stores the state ref. |

A bookmark or tag points at a **state object**:

```

State { version [0]: 1, heads [1]: [ChangeHash] }   // sorted, unique; may be empty

```

Every reference, attestation, view, and checkpoint therefore names a state by one ObjectRef however many heads it has. Multiple heads are normal in this model: every independent change is a head until something depends on it, so a busy bookmark may have dozens. That is not a conflict in the §9 sense; `oxy log` shows the heads as parallel, and a state object keeps the cost of naming them constant for everything that refers to the bookmark. The empty state, `State { heads: [] }`, is what a new bookmark points at.

Every published bookmark update is accompanied by an attestation (§14.4) of kind `ref` that binds the repository ID, the reference name, the previous state, the new state, and a per-reference monotonically increasing `serial`. Servers MUST store the latest attestation per reference and serve it with the reference. Clients MUST verify the attestation against policy before updating a `remotes/` reference and MUST reject an attestation whose `serial` is lower than one they have already recorded for that reference (rollback protection). Clients SHOULD warn when the newest attestation's `hlc.wall_ms` is older than `remote.max-age` (default 30 days) and the remote claims no update.

  view    [4]: { bookmarks: map<name, state ObjectRef>, remotes: map, tags: map, workspaces: map<WorkspaceId, ChangeHash> }

  format              "oxy repository format 2\n"

ref:    { name, old_state: ObjectRef, new_state: ObjectRef, serial: u64 }

tag:    { name, state: ObjectRef, message }

- A change or attestation is **authorized** for reference `r` if its signer is listed in the first rule whose pattern matches `r`, and the rule's threshold of distinct authorized signers is met across the attestation and each change in the closure of `new_state` not previously in the closure of `old_state`. `require` selects which authenticators count for changes: individual signatures only, seals only, or either. Every change MUST additionally satisfy the author-or-delegate rule of §14.4 regardless of `require`.

| `GET refs` | `{ patterns }` | `[ { name, state: ObjectRef, heads, attestation: Signed<Attest> } ]` plus the current `Signed<Policy>` |

On push, the server MUST, in order: verify that every change has a valid signature or seal from a key embedded in policy and satisfies the author-or-delegate rule (§14.4), verify the attestation for each reference, check that `old_state` matches its current state (compare-and-swap), check policy rules for the reference including `allow_conflicts`, check that every dependency of every change is either included or already stored, and only then update references atomically. A failure rejects the whole push.

Server policy is the trust policy (§14.5) plus server configuration for per-reference rules: protected patterns that additionally require CI status, forbid conflicted heads, forbid multiple heads, or forbid force (non-fast-forward) updates. A force update is a `ref` attestation whose `old_state` heads are not all in the closure of `new_state`.

*Changelog.* Draft 0.5 (2026-09-26): bookmarks and tags point at a `state` object naming the heads, so attestations, views, and references carry one ObjectRef per bookmark however many heads it has; repository format 2 records this, and format-1 repositories migrate on open.

Draft 0.4b (2026-09-26): §5.5 records the encoding conventions for variants, references, views, signatures, and secret key files; §13.1 adds the signature directory.