Compare main … identical-sides

// Cheap checks on the WASM tier (oxygenflow#96): OxygenFlow's checks module,

// copied from oxygenflow/.flow/checks.wasm (built there from

// crates/flow-checks; copy it again when it changes). No image and no KVM,

// so any runner with the WASM tier takes it: a phone, plex, windows-1.

sandbox "wasm" {

    runtime "wasm"

    memory-limit "64MiB"

}

// The changelog's shape, and a section for the version Cargo.toml says, so a

// release never finds its notes missing.

job "changelog" {

    sandbox "wasm"

    scope "CHANGELOG.md" "Cargo.toml" ".flow/checks.wasm"

    exec ".flow/checks.wasm" "changelog" "CHANGELOG.md" "Cargo.toml"

}

        }

        artifact "oxy-src.tar.gz" {

            path "/src/target/dist-flat/oxy-src.tar.gz"

## 0.11.0 (2026-11-04)

- **Changed: the changelog is checked on the WASM tier.** A `changelog` job in the pipeline runs OxygenFlow's checks module on any runner with the WASM tier, failing when the changelog's sections are out of shape or Cargo.toml's version has none.

- **Changed: moved subrepo pins are named (#162).** A pin moved by work inside a subrepo is a pin bump the parent's next commit records, and it used to go in unsaid. `oxy status` now lists it under *Subrepo pins* (old → new), and a subrepo's own uncommitted edits, which the parent does not record; a bare `oxy commit` that records a moved pin says so and how to leave it out (`oxy commit PATHS`).

- **Added: `oxy submodule remove --delete` (#164).** It deletes the subrepo's directory too, read-only object files and all, and refuses while the subrepo has uncommitted edits (`--force` to delete them anyway); without it, removal says the directory is left and how to delete it. A directory moved by hand used to fail halfway, after the copy, on the read-only files.

- **Changed: an agent's commit says "awaiting seal", not "unsigned" (#165).** In a checkout that signs keyless under an agent grant, a change of its own author that the next push will seal shows `◌ awaiting seal` in `oxy log` and `oxy show`; "unsigned" is kept for changes nothing will sign.

- **Fixed: a stale `author.key` can no longer fork your identity (#163).** A checkout that pinned `author.key` to a key a rotation made elsewhere had already succeeded built a second successor of it on `oxy identity delegate add`, splitting the identity in two. `rotate`, `renew` and `delegate add`/`remove` now refuse to start from a key that already has a successor in your home, naming the newest key and the `oxy config` that points at it; their report says which key they started from and which config named it; and `oxy identity show` warns when the configured key is not the newest, and names the key where an identity forks.

## 0.10.0 (2026-11-01)

- **Fixed: fetch, pull and clone are far faster with many bookmarks (#158).** They fetched each bookmark in its own exchange with the hub, and changes that bookmarks share were sent again for each one; a pull with nothing new still asked for a bundle per bookmark. Now every bookmark's heads are fetched in one exchange, and none when nothing is new. On a 47 MB repository with 160 bookmarks: a pull with nothing new 169 s → 3.5 s, a clone 324 s → 26 s. `OXY_TIMINGS` now also shows the refs, transparency log and per-bookmark checks of a fetch.

- **Added: `oxy git colocate`, a `.git` beside `.oxy` (oxygenhub#355).** Your editor's Git features (blame, history, gutter marks) and other Git tools now work on an Oxygen checkout: oxy keeps a `.git` there with the current bookmark exported after every command, Git's index at its tree so `git status` shows only your uncommitted work, and `.oxy/` excluded. One way: commit with oxy. `--off` stops it.

- **Changed: `.git` is never content.** oxy no longer picks up a `.git` directory at a checkout's top, and checkout refuses a path with a `.git` component at any depth (as Git does), so a change cannot plant Git hooks.

- **Added: a Git export from the change graph (oxygenhub#355).** oxy-core's `git_export_graph` writes every bookmark and tag to a bare Git repository so that the same changes give the same commits wherever it runs: each change a commit whose parents are its dependencies, each bookmark a branch (a merge of its heads when it has several), tags as tags, incrementally. It is what OxygenHub serves to `git clone`. (`oxy git export` still follows the checkout's own history.)

- **Added: `oxy mcp`, Oxygen for AI agents (#159).** An MCP server over stdio for a repository: an agent calls typed tools (status, diff, log, show, cat, blame, bookmarks, tags, conflicts, op log, identity, commit, amend, describe, fetch, pull, push, tlog verify) and gets each command's JSON back instead of reading a shell. It signs as the identity its environment configures, so started with an agent home every change is sealed via the agent with nothing to forget per command, and says who in its `initialize` reply. Commits name their paths (or `all: true`); undo and forced pushes are off unless started with `--allow-destructive`. The protocol itself is oxy-core's `mcp` module, for `oh mcp` to reuse. See docs/mcp.md.

- **Icons for HaikuDepot (#157).** `packaging/haikuports/icons/` has oxy's and oh's icons as HVIF (Haiku's vector format) with 16, 32 and 64 px PNGs, written by `make-icons.py`: the Oxygen mark on a pale tile for oxy, on OxygenHub's dark tile for oh, the same family as the VS Code extensions.

## 0.9.0 (2026-10-29)

- **Releases carry their source (#157).** Each release now has `oxy-VERSION-src.tar.gz`, the source as released, reproducible (sorted, fixed times and owners, gzip without a timestamp), listed in SHA256SUMS, for packagers to fetch at a fixed checksum. `packaging/haikuports/make-recipe.py oxy|oh TARBALL VERSION` writes the haikuports recipe from it (oh's from OxygenHub's source tarball); the 0.8.0 recipe, which used the on-demand archive, is gone.

- **Added: a haikuports recipe for oxy (#156).** `packaging/haikuports/` holds the recipe that builds oxy for HaikuDepot from the release source and every crate in `Cargo.lock`, and the script that writes it for a new release; the 0.8.0 recipe builds with haikuporter on Haiku R1/beta6.

- **Fixed: an expired checkout token no longer hides your sign-in (#155).** A checkout's own token for a remote (`remote.NAME.token`) is used first, so when it expired every fetch, pull and push answered 401 although `oxy auth login` had a good sign-in for the same hub. A checkout token the hub no longer knows (401) now falls back to that sign-in, with a warning naming `oxy config --unset remote.NAME.token` to drop the stale one; never to another checkout's token, and not when the token is refused for permission (403, 404), so a narrowly scoped token is never swapped for a wider sign-in. When both are refused, the error says to sign in again and unset it.

- **Added: the `artifact` object type (Cylinder C1, #108).** An artifact is now an object of its own in the store (oxy-core's `artifact` module), named by its object hash as every object is, and `oxy fsck` checks it; its tree stays a blob. Stores written before read as they did: the type is a new one at the end of the list.

- **Added: artifacts (Cylinder, step C1, #108).** `oxy artifact pack DIR --kind archive|package|container|runner-image|report [--arch --os --entrypoint --env K=V --label K=V]` packs a directory into an artifact: each file an ordinary blob of the repository's store, so files and chunks it holds already cost nothing, under a tree and an artifact encoding in canonical CBOR, named by the BLAKE3 of that encoding (docs/cylinder.md §4.1). `oxy artifact list | show NAME | unpack NAME DEST | verify NAME` (any unique prefix of six characters or more; `--json` on list, show and pack), and `oxy gc` keeps every artifact's blobs. The new `cylinder` crate holds the model.

- **Added: oxy on Haiku (#154).** oxy builds and runs on Haiku R1/beta6 (x86_64) with HaikuPorts' Rust; `oxy-VERSION-haiku-x86_64.tar.gz` is on the releases page from 0.8.0, with its own `SHA256SUMS-haiku`. The README says how to install it and how to build it (`ZSTD_SYS_USE_PKG_CONFIG=1`).

- **Fixed: a subrepo put back after its removal is pinned in the change that registers it (#152).** `oxy submodule remove` leaves a marker so the next snapshot drops the node while the directory stays; the snapshot cleared it only after reading it, so when nothing looked at the working copy between the removal's commit and the subrepo's return, the change that registered it again in `.oxymodules` left it out and a second commit was needed. A marker is now dropped before it is read once the removal is recorded or the path is registered again.

- **Fixed: `oxy identity create` needs no repository (#144).** Outside one it makes a user identity: the secret and identity go to the oxy home's keys and the user file names it as the author, so a new user or machine sets up an identity first; a repository made or cloned afterwards signs with it. Only `--local` needs a repository, and inside one it is kept there too, as before.

## 0.8.0 (2026-10-27)

- **A subrepo at its pinned state is unmodified on any bookmark (#147).** A subrepo whose heads were exactly its pin's but which sat on another bookmark than the pin named counted as modified, so `oxy bookmark switch` refused ("the working copy has changes"). Only the state counts now: the same repository at the same heads, or the same Git commit; the recorded pin stands.

name = "cylinder"

version = "0.11.0"

dependencies = [

 "blake3",

 "oxy-core",

 "tempfile",

 "thiserror 1.0.69",

]

[[package]]

version = "0.11.0"

 "cylinder",

version = "0.11.0"

version = "0.11.0"

version = "0.11.0"

members = ["crates/oxy-core", "crates/oxy-server", "crates/oxy-strata", "crates/cylinder", "."]

version = "0.11.0"

cylinder = { path = "crates/cylinder" }

An agent can also work through `oxy mcp`, an MCP server for the repository: typed tools instead of a shell, signing as the identity it was started with, and nothing destructive unless you allow it (see [docs/mcp.md](docs/mcp.md)).

Builds for Linux, macOS, Windows and Haiku are on the [releases page](https://oxygenhub.io/andymccall/oxygen/releases). These are early releases: the macOS and Windows builds are not signed and have had little testing.

- **Haiku** (R1/beta6, x86_64): unpack `oxy-VERSION-haiku-x86_64.tar.gz` and copy `oxy` to `~/config/non-packaged/bin`. It is built in a Haiku guest rather than by OxygenFlow, so it has its own `SHA256SUMS-haiku` and no build attestation.

On Haiku, install `rust_bin` and `zstd_devel` with pkgman and build with `ZSTD_SYS_USE_PKG_CONFIG=1 cargo build --release`: zstd-sys then links Haiku's libzstd, since a system library also references zstd and ld refuses the bundled copy's hidden symbols.

| `docs/mcp.md` | `oxy mcp`: the repository as tools for AI agents |

[package]

name = "cylinder"

version.workspace = true

edition.workspace = true

license.workspace = true

description = "Cylinder: artifacts as trees of Oxygen chunks (docs/cylinder.md)"

[dependencies]

oxy-core = { path = "../oxy-core" }

blake3 = "1"

thiserror = "1"

[dev-dependencies]

tempfile = "3"

//! Cylinder, step C1 (docs/cylinder.md §4.1): an **artifact** is an

//! immutable, content-addressed object naming a tree of files, each kept as

//! an ordinary Oxygen blob of FastCDC BLAKE3 chunks. An image rebuilt with

//! one changed file moves only that file's changed chunks, and a binary in

//! a release archive and in a runner image is the same chunks.

//!

//! The model is oxy-core's ([`oxy_core::artifact`]): an `artifact` object

//! in canonical CBOR, named by its object hash, whose tree is a blob. This

//! crate packs a directory into one, opens, verifies and unpacks it, and

//! keeps it: `.oxy/artifacts/NAME` records each artifact this repository

//! keeps, which garbage collection keeps with its tree and files

//! ([`roots`]).

use oxy_core::hash::{ObjectRef, ObjectType};

use oxy_core::repo::Repo;

use std::collections::BTreeMap;

use std::path::{Path, PathBuf};

pub use oxy_core::artifact::{

    Artifact, DirTree, Entry, Kind, MODE_EXEC, MODE_FILE, MODE_LINK, VERSION,

};

#[derive(Debug, thiserror::Error)]

pub enum Error {

    #[error(transparent)]

    Repo(#[from] oxy_core::repo::RepoError),

    #[error("io: {0}")]

    Io(#[from] std::io::Error),

    #[error("not an artifact: {0}")]

    Object(#[from] oxy_core::objects::ObjectError),

    #[error("store: {0}")]

    Store(#[from] oxy_core::store::StoreError),

    #[error("{0}")]

    Bad(String),

}

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

fn bad<T>(msg: impl Into<String>) -> Result<T> {

    Err(Error::Bad(msg.into()))

}

/// What to pack a directory as.

#[derive(Clone, Debug)]

pub struct Spec {

    pub kind: Kind,

    pub arch: Option<String>,

    pub os: Option<String>,

    pub entrypoint: Option<Vec<String>>,

    pub env: BTreeMap<String, String>,

    pub labels: BTreeMap<String, String>,

}

impl Spec {

    pub fn new(kind: Kind) -> Spec {

        Spec {

            kind,

            arch: None,

            os: None,

            entrypoint: None,

            env: BTreeMap::new(),

            labels: BTreeMap::new(),

        }

    }

}

/// An artifact kept in a repository, with its name.

#[derive(Clone, Debug)]

pub struct Kept {

    pub name: String,

    pub artifact: Artifact,

    /// Its object (its name, as a reference).

    pub object: ObjectRef,

}

fn kept_dir(repo: &Repo) -> PathBuf {

    repo.oxy_dir().join("artifacts")

}

/// Every file under `dir`, by relative path: regular files and links, in

/// path order. `.oxy` and `.git` directories are not part of an artifact.

fn walk(dir: &Path) -> Result<Vec<(String, PathBuf, std::fs::Metadata)>> {

    let mut out = Vec::new();

    let mut stack = vec![(dir.to_path_buf(), String::new())];

    while let Some((d, rel)) = stack.pop() {

        for e in std::fs::read_dir(&d)? {

            let e = e?;

            let name = e

                .file_name()

                .into_string()

                .map_err(|n| Error::Bad(format!("{n:?} is not UTF-8")))?;

            let path = if rel.is_empty() {

                name.clone()

            } else {

                format!("{rel}/{name}")

            };

            let md = std::fs::symlink_metadata(e.path())?;

            if md.is_dir() {

                if name != ".oxy" && name != ".git" {

                    stack.push((e.path(), path));

                }

            } else if md.is_file() || md.file_type().is_symlink() {

                out.push((path, e.path(), md));

            }

        }

    }

    out.sort_by(|a, b| a.0.cmp(&b.0));

    Ok(out)

}

#[cfg(unix)]

fn mode_of(md: &std::fs::Metadata) -> u32 {

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

    if md.file_type().is_symlink() {

        MODE_LINK

    } else if md.permissions().mode() & 0o111 != 0 {

        MODE_EXEC

    } else {

        MODE_FILE

    }

}

#[cfg(not(unix))]

fn mode_of(md: &std::fs::Metadata) -> u32 {

    if md.file_type().is_symlink() {

        MODE_LINK

    } else {

        MODE_FILE

    }

}

/// Pack the files under `dir` into an artifact of `spec`'s kind in

/// `repo`'s store: each file a blob, so files and chunks the store holds

/// already cost nothing; then its tree and its encoding, kept under its

/// name.

pub fn pack(repo: &Repo, dir: &Path, spec: &Spec) -> Result<Kept> {

    if !dir.is_dir() {

        return bad(format!("{} is not a directory", dir.display()));

    }

    let mut tree = DirTree::default();

    for (path, full, md) in walk(dir)? {

        let mode = mode_of(&md);

        let bytes = if mode == MODE_LINK {

            std::fs::read_link(&full)?

                .to_string_lossy()

                .into_owned()

                .into_bytes()

        } else {

            std::fs::read(&full)?

        };

        let blob = repo.store_blob(&bytes)?;

        tree.entries.push(Entry {

            path,

            mode,

            blob,

            size: bytes.len() as u64,

        });

    }

    let artifact = Artifact {

        kind: spec.kind,

        arch: spec.arch.clone(),

        os: spec.os.clone(),

        tree: repo.store_blob(&tree.encode())?,

        entrypoint: spec.entrypoint.clone(),

        env: spec.env.clone(),

        labels: spec.labels.clone(),

        total_size: tree.entries.iter().map(|e| e.size).sum(),

        receipt: None,

    };

    let object = repo.store().put(ObjectType::Artifact, &artifact.encode())?;

    let name = object.to_hex();

    std::fs::create_dir_all(kept_dir(repo))?;

    std::fs::write(kept_dir(repo).join(&name), b"")?;

    Ok(Kept {

        name,

        artifact,

        object,

    })

}

/// The names of the artifacts kept in `repo`, sorted.

pub fn list(repo: &Repo) -> Result<Vec<String>> {

    let mut out = Vec::new();

    match std::fs::read_dir(kept_dir(repo)) {

        Ok(rd) => {

            for e in rd {

                let n = e?.file_name().to_string_lossy().into_owned();

                if n.len() == 64 && n.bytes().all(|b| b.is_ascii_hexdigit()) {

                    out.push(n);

                }

            }

        }

        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}

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

    }

    out.sort();

    Ok(out)

}

/// The kept artifact `name` names, or a unique prefix of it (at least six

/// characters), read from the store, which checks it against its name.

pub fn open(repo: &Repo, name: &str) -> Result<Kept> {

    let name = name.to_ascii_lowercase();

    if name.len() < 6 {

        return bad("name an artifact by at least six characters of its name");

    }

    let found: Vec<String> = list(repo)?

        .into_iter()

        .filter(|n| n.starts_with(&name))

        .collect();

    let full = match found.as_slice() {

        [one] => one.clone(),

        [] => {

            return bad(format!(

                "no artifact {name} here; `oxy artifact list` shows them"

            ))

        }

        _ => {

            return bad(format!(

                "{name} names {} artifacts: give more of the name",

                found.len()

            ))

        }

    };

    let object = ObjectRef::from_hex(&full).map_or_else(

        || bad(format!("artifact {full}: its record is damaged")),

        Ok,

    )?;

    // The store checks the bytes against the object's name as it reads.

    let bytes = repo.store().get_typed(&object, ObjectType::Artifact)?;

    Ok(Kept {

        name: full,

        artifact: Artifact::decode(&bytes)?,

        object,

    })

}

/// An artifact's tree.

pub fn tree(repo: &Repo, a: &Artifact) -> Result<DirTree> {

    Ok(DirTree::decode(&repo.read_blob(&a.tree)?)?)

}

/// Check that every file of `k` is in the store whole: its bytes read, at

/// the size its tree says. Answers how many files were read.

pub fn verify(repo: &Repo, k: &Kept) -> Result<usize> {

    let t = tree(repo, &k.artifact)?;

    let mut total = 0;

    for e in &t.entries {

        let n = repo.read_blob(&e.blob)?.len() as u64;

        if n != e.size {

            return bad(format!(

                "{}: {n} bytes, but the tree says {}",

                e.path, e.size

            ));

        }

        total += n;

    }

    if total != k.artifact.total_size {

        return bad(format!(

            "the files are {total} bytes together, but the artifact says {}",

            k.artifact.total_size

        ));

    }

    Ok(t.entries.len())

}

/// Write `k`'s files under `dest`, which must not exist or be empty.

pub fn unpack(repo: &Repo, k: &Kept, dest: &Path) -> Result<usize> {

    if dest.exists() && std::fs::read_dir(dest)?.next().is_some() {

        return bad(format!("{} is not empty", dest.display()));

    }

    let t = tree(repo, &k.artifact)?;

    for e in &t.entries {

        let out = dest.join(&e.path);

        if let Some(p) = out.parent() {

            std::fs::create_dir_all(p)?;

        }

        let bytes = repo.read_blob(&e.blob)?;

        if e.mode == MODE_LINK {

            #[cfg(unix)]

            std::os::unix::fs::symlink(String::from_utf8_lossy(&bytes).as_ref(), &out)?;

            #[cfg(not(unix))]

            std::fs::write(&out, &bytes)?;

            continue;

        }

        std::fs::write(&out, &bytes)?;

        #[cfg(unix)]

        if e.mode == MODE_EXEC {

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

            std::fs::set_permissions(&out, std::fs::Permissions::from_mode(0o755))?;

        }

    }

    Ok(t.entries.len())

}

/// The blobs garbage collection must keep for the kept artifacts: each

/// one's encoding, its tree and its files (`Repo::gc_keeping`).

pub fn roots(repo: &Repo) -> Result<Vec<ObjectRef>> {

    let mut out = Vec::new();

    for name in list(repo)? {

        let k = open(repo, &name)?;

        out.push(k.object);

        out.push(k.artifact.tree);

        out.extend(tree(repo, &k.artifact)?.entries.iter().map(|e| e.blob));

    }

    Ok(out)

}

#[cfg(test)]

mod tests {

    use super::*;

    use oxy_core::cbor::{self, Value};

    fn repo(dir: &Path) -> Repo {

        Repo::init(&dir.join("repo")).unwrap()

    }

    #[test]

    fn a_directory_packs_into_an_artifact_and_back() {

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

        let r = repo(t.path());

        let src = t.path().join("out");

        std::fs::create_dir_all(src.join("bin")).unwrap();

        std::fs::write(src.join("README"), b"hello\n").unwrap();

        std::fs::write(src.join("bin/tool"), vec![7u8; 300_000]).unwrap();

        #[cfg(unix)]

        {

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

            std::fs::set_permissions(src.join("bin/tool"), std::fs::Permissions::from_mode(0o755))

                .unwrap();

            std::os::unix::fs::symlink("bin/tool", src.join("tool")).unwrap();

        }

        let mut spec = Spec::new(Kind::Archive);

        spec.arch = Some("x86_64".into());

        spec.labels.insert("version".into(), "0.1.0".into());

        let k = pack(&r, &src, &spec).unwrap();

        assert_eq!(k.name, k.artifact.name().to_hex());

        assert_eq!(

            k.artifact.total_size,

            300_006 + if cfg!(unix) { 8 } else { 0 }

        );

        assert_eq!(list(&r).unwrap(), vec![k.name.clone()]);

        let again = open(&r, &k.name[..10]).unwrap();

        assert_eq!(again.artifact, k.artifact);

        let paths: Vec<(String, u32)> = tree(&r, &again.artifact)

            .unwrap()

            .entries

            .into_iter()

            .map(|e| (e.path, e.mode))

            .collect();

        assert_eq!(paths[0], ("README".into(), MODE_FILE));

        assert_eq!(

            paths[1],

            (

                "bin/tool".into(),

                if cfg!(unix) { MODE_EXEC } else { MODE_FILE }

            )

        );

        assert_eq!(verify(&r, &again).unwrap(), paths.len());

        let dest = t.path().join("back");

        unpack(&r, &again, &dest).unwrap();

        assert_eq!(

            std::fs::read(dest.join("bin/tool")).unwrap(),

            vec![7u8; 300_000]

        );

        #[cfg(unix)]

        assert_eq!(

            std::fs::read_link(dest.join("tool")).unwrap(),

            Path::new("bin/tool")

        );

        assert!(unpack(&r, &again, &dest)

            .unwrap_err()

            .to_string()

            .contains("not empty"));

        // The same files pack to the same name; garbage collection keeps it.

        assert_eq!(pack(&r, &src, &spec).unwrap().name, k.name);

        let keep = roots(&r).unwrap();

        assert!(keep.contains(&k.object) && keep.contains(&k.artifact.tree));

        r.gc_keeping(true, &keep, &mut |_| {}).unwrap();

        // An artifact is an object of its own, which fsck reads and accepts.

        let report = r.fsck().unwrap();

        let errors: Vec<_> = report

            .problems

            .iter()

            .filter(|p| p.severity == oxy_core::repo::Severity::Error)

            .collect();

        assert!(errors.is_empty(), "{errors:?}");

        assert_eq!(

            verify(&r, &open(&r, &k.name).unwrap()).unwrap(),

            paths.len()

        );

    }

    #[test]

    fn encodings_are_canonical_and_checked() {

        let a = Artifact {

            kind: Kind::RunnerImage,

            arch: Some("riscv64".into()),

            os: Some("linux".into()),

            tree: ObjectRef([1; 32]),

            entrypoint: Some(vec!["/sbin/init".into()]),

            env: [("PATH".to_string(), "/bin".to_string())].into(),

            labels: BTreeMap::new(),

            total_size: 42,

            receipt: Some(ObjectRef([2; 32])),

        };

        let bytes = a.encode();

        assert_eq!(Artifact::decode(&bytes).unwrap(), a);

        assert_eq!(

            a.name(),

            oxy_core::hash::hash_object(ObjectType::Artifact, &bytes)

        );

        assert!(Kind::parse("tarball")

            .unwrap_err()

            .to_string()

            .contains("runner-image"));

        let wrong = |v: Value| Artifact::decode(&cbor::encode(&v)).unwrap_err().to_string();

        assert!(wrong(Value::map([(0, Value::Uint(2))])).contains("version"));

        assert!(wrong(Value::map([(0, Value::Uint(1)), (10, Value::Null)])).contains("key 10"));

        let t = DirTree {

            entries: vec![Entry {

                path: "a".into(),

                mode: MODE_FILE,

                blob: ObjectRef([3; 32]),

                size: 1,

            }],

        };

        assert_eq!(DirTree::decode(&t.encode()).unwrap(), t);

        let entry = |p: &str, mode: u32| {

            Value::Array(vec![

                Value::Text(p.into()),

                Value::Uint(mode as u64),

                Value::Bytes(vec![0; 32]),

                Value::Uint(0),

            ])

        };

        let tree = |items: Vec<Value>| {

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

                (0, Value::Uint(1)),

                (1, Value::Array(items)),

            ])))

            .unwrap_err()

            .to_string()

        };

        assert!(tree(vec![entry("../x", MODE_FILE)]).contains("clean"));

        assert!(tree(vec![entry("b", MODE_FILE), entry("a", MODE_FILE)]).contains("order"));

        assert!(tree(vec![entry("a", 0o040000)]).contains("mode"));

    }

}

//! Artifacts (Cylinder, docs/cylinder.md §4.1, oxygen#108): an immutable

//! object naming a tree of files, each an ordinary blob of FastCDC BLAKE3

//! chunks, so an image rebuilt with one changed file moves only that file's

//! changed chunks, and a binary in an archive and in an image is the same

//! chunks. An artifact is an object of its own (`artifact`) in canonical

//! CBOR; its tree is a blob. The `cylinder` crate packs, unpacks and keeps

//! them.

use crate::cbor::{self, Value};

use crate::hash::{hash_object, ObjectRef, ObjectType};

use crate::objects::{schema, ObjectError};

use std::collections::BTreeMap;

type R<T> = std::result::Result<T, ObjectError>;

/// The encoding's version this crate writes and reads.

pub const VERSION: u64 = 1;

/// What an artifact is for.

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

pub enum Kind {

    Container,

    RunnerImage,

    Package,

    Archive,

    Report,

}

impl Kind {

    pub const ALL: [Kind; 5] = [

        Kind::Container,

        Kind::RunnerImage,

        Kind::Package,

        Kind::Archive,

        Kind::Report,

    ];

    pub fn as_str(self) -> &'static str {

        match self {

            Kind::Container => "container",

            Kind::RunnerImage => "runner-image",

            Kind::Package => "package",

            Kind::Archive => "archive",

            Kind::Report => "report",

        }

    }

    pub fn parse(s: &str) -> R<Kind> {

        Kind::ALL.into_iter().find(|k| k.as_str() == s).map_or_else(

            || {

                schema(format!(

                    "{s:?} is not a kind of artifact: {}",

                    Kind::ALL.map(|k| k.as_str()).join(", ")

                ))

            },

            Ok,

        )

    }

}

/// A file's mode in a tree: a regular file, an executable one, or a

/// symbolic link (whose blob is its target).

pub const MODE_FILE: u32 = 0o100644;

pub const MODE_EXEC: u32 = 0o100755;

pub const MODE_LINK: u32 = 0o120000;

/// A file of an artifact's tree.

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

pub struct Entry {

    /// `/`-separated, relative, never `.` or `..` parts.

    pub path: String,

    pub mode: u32,

    pub blob: ObjectRef,

    pub size: u64,

}

/// An artifact's files, in path order: paths, modes, blobs and sizes.

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

pub struct DirTree {

    pub entries: Vec<Entry>,

}

fn path_ok(p: &str) -> bool {

    !p.is_empty()

        && !p.starts_with('/')

        && p.split('/').all(|s| !s.is_empty() && s != "." && s != "..")

}

fn obj(r: &ObjectRef) -> Value {

    Value::Bytes(r.0.to_vec())

}

fn get_obj(v: &Value, what: &str) -> R<ObjectRef> {

    match v.as_bytes() {

        Some(b) if b.len() == 32 => {

            let mut a = [0u8; 32];

            a.copy_from_slice(b);

            Ok(ObjectRef(a))

        }

        _ => schema(format!("{what} is not an object reference")),

    }

}

fn get_text(v: &Value, what: &str) -> R<String> {

    v.as_text()

        .map(str::to_string)

        .map_or_else(|| schema(format!("{what} is not text")), Ok)

}

fn get_uint(v: &Value, what: &str) -> R<u64> {

    v.as_uint()

        .map_or_else(|| schema(format!("{what} is not a number")), Ok)

}

impl DirTree {

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

        let entries = self

            .entries

            .iter()

            .map(|e| {

                Value::Array(vec![

                    Value::Text(e.path.clone()),

                    Value::Uint(e.mode as u64),

                    obj(&e.blob),

                    Value::Uint(e.size),

                ])

            })

            .collect();

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

            (0, Value::Uint(VERSION)),

            (1, Value::Array(entries)),

        ]))

    }

    /// Read and check a tree: a known version, clean paths, each once, in

    /// order, with a known mode.

    pub fn decode(bytes: &[u8]) -> R<DirTree> {

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

        let m = v.as_map().map_or_else(|| schema("a tree is a map"), Ok)?;

        if m.get(&0).and_then(Value::as_uint) != Some(VERSION) {

            return schema(format!(

                "tree version {:?} is not known; this reads {VERSION}",

                m.get(&0)

            ));

        }

        let mut entries = Vec::new();

        for item in m.get(&1).and_then(Value::as_array).unwrap_or_default() {

            let [p, mode, blob, size] = item.as_array().unwrap_or_default() else {

                return schema("a tree entry is [path, mode, blob, size]");

            };

            let path = get_text(p, "a path")?;

            let mode = get_uint(mode, "a mode")? as u32;

            if !path_ok(&path) {

                return schema(format!("{path:?} is not a clean relative path"));

            }

            if ![MODE_FILE, MODE_EXEC, MODE_LINK].contains(&mode) {

                return schema(format!(

                    "{path}: mode {mode:o} is not a file, an executable or a link"

                ));

            }

            if entries.last().is_some_and(|l: &Entry| l.path >= path) {

                return schema(format!(

                    "{path}: entries are not in path order, or one is there twice"

                ));

            }

            entries.push(Entry {

                path,

                mode,

                blob: get_obj(blob, "a blob")?,

                size: get_uint(size, "a size")?,

            });

        }

        Ok(DirTree { entries })

    }

}

/// An artifact (docs/cylinder.md §4.1).

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

pub struct Artifact {

    pub kind: Kind,

    /// `x86_64`, `riscv64`, `aarch64`.

    pub arch: Option<String>,

    /// `linux`, `darwin`, `none`.

    pub os: Option<String>,

    /// The [`DirTree`]'s blob.

    pub tree: ObjectRef,

    /// The default command, for a container or an image.

    pub entrypoint: Option<Vec<String>>,

    pub env: BTreeMap<String, String>,

    pub labels: BTreeMap<String, String>,

    /// The files' bytes together.

    pub total_size: u64,

    /// The receipt of the Flow job that built it, when one did.

    pub receipt: Option<ObjectRef>,

}

fn pairs(m: &BTreeMap<String, String>) -> Value {

    if m.is_empty() {

        return Value::Null;

    }

    Value::Array(

        m.iter()

            .map(|(k, v)| Value::Array(vec![Value::Text(k.clone()), Value::Text(v.clone())]))

            .collect(),

    )

}

fn get_pairs(v: Option<&Value>, what: &str) -> R<BTreeMap<String, String>> {

    let mut out = BTreeMap::new();

    let Some(v) = v.filter(|v| !v.is_null()) else {

        return Ok(out);

    };

    for p in v

        .as_array()

        .map_or_else(|| schema(format!("{what} is a list of pairs")), Ok)?

    {

        let [k, val] = p.as_array().unwrap_or_default() else {

            return schema(format!("{what}: a pair is [key, value]"));

        };

        let k = get_text(k, what)?;

        if out.insert(k.clone(), get_text(val, what)?).is_some() {

            return schema(format!("{what}: {k} is there twice"));

        }

    }

    Ok(out)

}

fn opt_text(v: &Option<String>) -> Value {

    v.as_ref().map_or(Value::Null, |s| Value::Text(s.clone()))

}

impl Artifact {

    /// Its canonical CBOR, keys as in docs/cylinder.md §4.1.

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

        let entry = self.entrypoint.as_ref().map_or(Value::Null, |a| {

            Value::Array(a.iter().cloned().map(Value::Text).collect())

        });

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

            (0, Value::Uint(VERSION)),

            (1, Value::Text(self.kind.as_str().into())),

            (2, opt_text(&self.arch)),

            (3, opt_text(&self.os)),

            (4, obj(&self.tree)),

            (5, entry),

            (6, pairs(&self.env)),

            (7, pairs(&self.labels)),

            (8, Value::Uint(self.total_size)),

            (9, self.receipt.as_ref().map_or(Value::Null, obj)),

        ]))

    }

    pub fn decode(bytes: &[u8]) -> R<Artifact> {

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

        let m = v

            .as_map()

            .map_or_else(|| schema("an artifact is a map"), Ok)?;

        if m.get(&0).and_then(Value::as_uint) != Some(VERSION) {

            return schema(format!(

                "artifact version {:?} is not known; this reads {VERSION}",

                m.get(&0)

            ));

        }

        if let Some(k) = m.keys().find(|k| **k > 9) {

            return schema(format!("key {k} is not part of an artifact"));

        }

        let text = |k: u64, what: &str| -> R<Option<String>> {

            match m.get(&k) {

                None | Some(Value::Null) => Ok(None),

                Some(v) => get_text(v, what).map(Some),

            }

        };

        let entrypoint = match m.get(&5) {

            None | Some(Value::Null) => None,

            Some(v) => Some(

                v.as_array()

                    .unwrap_or_default()

                    .iter()

                    .map(|a| get_text(a, "the entrypoint"))

                    .collect::<R<_>>()?,

            ),

        };

        let receipt = match m.get(&9) {

            None | Some(Value::Null) => None,

            Some(v) => Some(get_obj(v, "the receipt")?),

        };

        Ok(Artifact {

            kind: Kind::parse(&text(1, "the kind")?.unwrap_or_default())?,

            arch: text(2, "the architecture")?,

            os: text(3, "the system")?,

            tree: get_obj(m.get(&4).unwrap_or(&Value::Null), "the tree")?,

            entrypoint,

            env: get_pairs(m.get(&6), "env")?,

            labels: get_pairs(m.get(&7), "labels")?,

            total_size: get_uint(m.get(&8).unwrap_or(&Value::Null), "the size")?,

            receipt,

        })

    }

    /// Its name: its object's hash, as every Oxygen object is named.

    pub fn name(&self) -> ObjectRef {

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

    }

}

    /// A tree of files as one immutable thing: an image, a package, an

    /// archive (Cylinder, docs/cylinder.md §4.1).

    Artifact,

    pub const ALL: [ObjectType; 13] = [

        ObjectType::Artifact,

            ObjectType::Artifact => "artifact",

pub mod artifact;

pub mod mcp;

//! A Model Context Protocol server over stdio (oxygen#159): JSON-RPC 2.0,

//! one message per line, as MCP's stdio transport has it. This is only the

//! protocol: `initialize`, `ping`, `tools/list` and `tools/call`, with the

//! tools themselves supplied by the caller (`oxy mcp`, and `oh mcp` in the

//! hub, which reaches this module through its pinned oxygen).

//!

//! Nothing is written to stdout but protocol messages: a tool's own

//! output goes into its result.

use serde_json::{json, Value};

use std::io::{BufRead, Write};

/// The protocol versions this server speaks, newest first. A client asking

/// for one of them gets it back; any other gets the newest.

pub const PROTOCOL_VERSIONS: &[&str] = &["2025-06-18", "2025-03-26", "2024-11-05"];

/// One tool as `tools/list` describes it.

#[derive(Clone, Debug)]

pub struct Tool {

    pub name: String,

    pub description: String,

    /// A JSON Schema object for the arguments.

    pub input_schema: Value,

    /// Reads only: no change to the repository, the remote or the hub.

    pub read_only: bool,

    /// May lose work or history (undo, abandon, deletes).

    pub destructive: bool,

}

impl Tool {

    fn describe(&self) -> Value {

        json!({

            "name": self.name,

            "description": self.description,

            "inputSchema": self.input_schema,

            "annotations": {

                "readOnlyHint": self.read_only,

                "destructiveHint": self.destructive,

            },

        })

    }

}

/// What a tool call produced: text for the model to read, the same as JSON

/// when there is some, and whether it failed. A failed tool is a result, not

/// a protocol error, so the model sees why.

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

pub struct ToolOutput {

    pub text: String,

    pub structured: Option<Value>,

    pub is_error: bool,

}

impl ToolOutput {

    pub fn ok(text: impl Into<String>) -> ToolOutput {

        ToolOutput {

            text: text.into(),

            structured: None,

            is_error: false,

        }

    }

    pub fn error(text: impl Into<String>) -> ToolOutput {

        ToolOutput {

            text: text.into(),

            structured: None,

            is_error: true,

        }

    }

    fn to_json(&self) -> Value {

        let mut out = json!({

            "content": [{ "type": "text", "text": self.text }],

            "isError": self.is_error,

        });

        // Structured content must be an object; an array is wrapped.

        if let Some(s) = &self.structured {

            let obj = if s.is_object() {

                s.clone()

            } else {

                json!({ "result": s })

            };

            out["structuredContent"] = obj;

        }

        out

    }

}

/// The tools a server offers.

pub trait Tools {

    fn list(&self) -> Vec<Tool>;

    /// Run a tool. `None` when no tool has that name.

    fn call(&self, name: &str, args: &Value) -> Option<ToolOutput>;

}

/// Who the server is, for `initialize`.

#[derive(Clone, Debug)]

pub struct ServerInfo {

    pub name: String,

    pub version: String,

    /// Shown to the model: what the server is for and how to use it safely.

    pub instructions: String,

}

const PARSE_ERROR: i64 = -32700;

const INVALID_REQUEST: i64 = -32600;

const METHOD_NOT_FOUND: i64 = -32601;

const INVALID_PARAMS: i64 = -32602;

fn error(id: Value, code: i64, message: &str) -> Value {

    json!({ "jsonrpc": "2.0", "id": id, "error": { "code": code, "message": message } })

}

fn result(id: Value, result: Value) -> Value {

    json!({ "jsonrpc": "2.0", "id": id, "result": result })

}

/// Answer one message; `None` for a notification (no reply is due).

pub fn handle(info: &ServerInfo, tools: &dyn Tools, message: &Value) -> Option<Value> {

    let Some(obj) = message.as_object() else {

        return Some(error(

            Value::Null,

            INVALID_REQUEST,

            "a message is a JSON object",

        ));

    };

    let method = obj.get("method").and_then(Value::as_str);

    let id = obj.get("id").cloned();

    let Some(method) = method else {

        // A response to something we never sent, or nonsense: a request

        // without a method gets an error, anything else is ignored.

        return id.map(|id| error(id, INVALID_REQUEST, "a request needs a method"));

    };

    // Notifications (initialized, cancelled, …) carry no id and get no reply.

    let id = id?;

    let params = obj.get("params").cloned().unwrap_or(Value::Null);

    Some(match method {

        "initialize" => {

            let asked = params.get("protocolVersion").and_then(Value::as_str);

            let version = asked

                .filter(|v| PROTOCOL_VERSIONS.contains(v))

                .unwrap_or(PROTOCOL_VERSIONS[0]);

            result(

                id,

                json!({

                    "protocolVersion": version,

                    "capabilities": { "tools": { "listChanged": false } },

                    "serverInfo": { "name": info.name, "version": info.version },

                    "instructions": info.instructions,

                }),

            )

        }

        "ping" => result(id, json!({})),

        "tools/list" => result(

            id,

            json!({ "tools": tools.list().iter().map(Tool::describe).collect::<Vec<_>>() }),

        ),

        "tools/call" => {

            let Some(name) = params.get("name").and_then(Value::as_str) else {

                return Some(error(

                    id,

                    INVALID_PARAMS,

                    "tools/call needs the tool's name",

                ));

            };

            let args = params

                .get("arguments")

                .cloned()

                .unwrap_or_else(|| json!({}));

            if !args.is_object() {

                return Some(error(

                    id,

                    INVALID_PARAMS,

                    "a tool's arguments are a JSON object",

                ));

            }

            match tools.call(name, &args) {

                Some(out) => result(id, out.to_json()),

                None => error(id, INVALID_PARAMS, &format!("no tool named {name}")),

            }

        }

        other => error(id, METHOD_NOT_FOUND, &format!("{other} is not supported")),

    })

}

/// Serve until the input ends: read a message per line, write a reply per

/// request. A line that is not JSON gets a parse error; blank lines are

/// skipped.

pub fn serve(

    info: &ServerInfo,

    tools: &dyn Tools,

    input: impl BufRead,

    mut output: impl Write,

) -> std::io::Result<()> {

    for line in input.lines() {

        let line = line?;

        if line.trim().is_empty() {

            continue;

        }

        let reply = match serde_json::from_str::<Value>(&line) {

            Ok(Value::Array(batch)) => {

                let replies: Vec<Value> = batch

                    .iter()

                    .filter_map(|m| handle(info, tools, m))

                    .collect();

                (!replies.is_empty()).then_some(Value::Array(replies))

            }

            Ok(message) => handle(info, tools, &message),

            Err(e) => Some(error(Value::Null, PARSE_ERROR, &format!("not JSON: {e}"))),

        };

        if let Some(reply) = reply {

            writeln!(output, "{reply}")?;

            output.flush()?;

        }

    }

    Ok(())

}

/// A string argument, if given and a string.

pub fn arg_str<'a>(args: &'a Value, key: &str) -> Option<&'a str> {

    args.get(key).and_then(Value::as_str)

}

/// A list of strings, if given; a single string counts as a list of one.

pub fn arg_strings(args: &Value, key: &str) -> Result<Vec<String>, String> {

    match args.get(key) {

        None | Some(Value::Null) => Ok(vec![]),

        Some(Value::String(s)) => Ok(vec![s.clone()]),

        Some(Value::Array(a)) => a

            .iter()

            .map(|v| {

                v.as_str()

                    .map(str::to_string)

                    .ok_or_else(|| format!("{key} must be a list of strings"))

            })

            .collect(),

        Some(_) => Err(format!("{key} must be a list of strings")),

    }

}

#[cfg(test)]

mod tests {

    use super::*;

    struct Echo;

    impl Tools for Echo {

        fn list(&self) -> Vec<Tool> {

            vec![Tool {

                name: "echo".into(),

                description: "says it back".into(),

                input_schema: json!({"type": "object"}),

                read_only: true,

                destructive: false,

            }]

        }

        fn call(&self, name: &str, args: &Value) -> Option<ToolOutput> {

            (name == "echo").then(|| ToolOutput {

                text: args.to_string(),

                structured: Some(json!([1, 2])),

                is_error: false,

            })

        }

    }

    fn info() -> ServerInfo {

        ServerInfo {

            name: "t".into(),

            version: "1".into(),

            instructions: "be careful".into(),

        }

    }

    fn talk(lines: &str) -> Vec<Value> {

        let mut out = Vec::new();

        serve(&info(), &Echo, lines.as_bytes(), &mut out).unwrap();

        String::from_utf8(out)

            .unwrap()

            .lines()

            .map(|l| serde_json::from_str(l).unwrap())