Bare repositories and an embeddable protocol server for Oxygenhub e02bf0cd0533

        self.blame_state(path, &snap.base, &snap.base_snapshot, "the working copy's base state")

    }

    /// Blame `path` in the state with these heads (hosted repositories).

    pub fn blame_in(&self, path: &str, heads: &[ChangeHash]) -> Result<Vec<BlameLine>> {

        let state = self.load_state(heads)?;

        let snapshot = state.materialize();

        self.blame_state(path, &state, &snapshot, "that state")

    }

    fn blame_state(&self, path: &str, state: &crate::state::State, snapshot: &crate::state::Snapshot, what: &str) -> Result<Vec<BlameLine>> {

        let Some(f) = snapshot.files.get(path) else { return fail(format!("{path} is not in {what}")) };

        for (i, ((hash, index), text)) in state.live_lines(&f.node).into_iter().enumerate() {

            let meta = state.get(&hash);

    /// A hosted repository with no working copy (spec §12.2, hub spec §4.1).

    bare: bool,

/// Marker file of a bare repository, inside `.oxy/`.

const BARE_MARKER: &str = "bare";

        let repo = Repo { git_export_skipped: Default::default(), root, oxy, store, workspace, bare: false, keys_dir: default_keys_dir(), user_config: default_user_config(), config };

    /// Create a bare repository: an object store, operation log and

    /// references with no workspace and no working copy, for hosting

    /// (hub spec §4.1). `root` holds `.oxy/` and nothing else.

    pub fn init_bare(root: &Path) -> Result<Repo> {

        let mut id = [0u8; 16];

        rand::rngs::OsRng.fill_bytes(&mut id);

        Self::init_bare_with_id(root, id)

    }

    pub fn init_bare_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())?;

        write_atomic(&oxy.join(BARE_MARKER), b"")?;

        let config = Config::load(Some(&default_user_config()), &oxy.join("config"))?;

        config.save(&oxy.join("config"))?;

        let store = Store::open(oxy.join("objects"))?;

        let repo = Repo { git_export_skipped: Default::default(), root, oxy, store, workspace: WorkspaceId::ZERO, bare: true, keys_dir: default_keys_dir(), user_config: default_user_config(), config };

        let mut view = View::default();

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

        repo.record_op(&[], "oxy init --bare", view)?;

        Ok(repo)

    }

    /// Whether this repository has no working copy (`init_bare`).

    pub fn is_bare(&self) -> bool {

        self.bare

    }

                let mut repo = Repo { git_export_skipped: Default::default(), root: d.to_path_buf(), oxy: shared, store, workspace, bare: false, keys_dir: default_keys_dir(), user_config: default_user_config(), config };

                let bare = oxy.join(BARE_MARKER).is_file();

                let workspace = if bare {

                    WorkspaceId::ZERO

                } else {

                    WorkspaceId::from_hex(fs::read_to_string(oxy.join("workspace"))?.trim()).ok_or_else(|| RepoError::Msg("corrupt .oxy/workspace".into()))?

                };

                let mut repo = Repo { git_export_skipped: Default::default(), root: d.to_path_buf(), oxy, store, workspace, bare, keys_dir: default_keys_dir(), user_config: default_user_config(), config };

                if !bare {

                    repo.apply_workspace_bookmark();

                }

        if self.bare {

            return fail("this is a bare repository: it has no working copy");

        }

        let heads = self.bookmark_heads()?;

        if self.bare {

            return self.log_state(&heads);

        }

        let mut all = heads.clone();

        all.push(wc_hash);

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

        let head_set: BTreeSet<ChangeHash> = heads.into_iter().collect();

    /// The log of the state with these heads, newest first, with no working

    /// copy involved (for hosted repositories and any explicit state).

    pub fn log_state(&self, heads: &[ChangeHash]) -> Result<Vec<LogEntry>> {

        let state = self.load_state(heads)?;

        let head_set: BTreeSet<ChangeHash> = state.heads().into_iter().collect();

        let mut entries: Vec<LogEntry> = state

            .changes()

            .map(|(h, meta)| LogEntry { hash: *h, change: meta.clone(), is_working_copy: false, is_head: head_set.contains(h) })

            .collect();

        entries.sort_by(|a, b| b.change.hlc.cmp(&a.change.hlc).then(b.hash.cmp(&a.hash)));

        Ok(entries)

    }

        let heads = self.bookmark_heads()?;

        if self.is_bare() {

            return self.log_for_path_in(path, &heads);

        }

        Ok(self.entries_touching(entries, node))

    }

    /// The log of the state with these heads restricted to changes touching

    /// `path` (its node, so renames are followed).

    pub fn log_for_path_in(&self, path: &str, heads: &[ChangeHash]) -> Result<Vec<LogEntry>> {

        let entries = self.log_state(heads)?;

        let snapshot = self.load_state(heads)?.materialize();

        let Some(node) = snapshot.files.get(path).map(|f| f.node) else { return fail(format!("{path} is not in that state")) };

        Ok(self.entries_touching(entries, node))

    }

    fn entries_touching(&self, entries: Vec<LogEntry>, node: NodeId) -> Vec<LogEntry> {

        out

//!

//! Hosts embed the protocol by implementing [`Backend`] (name resolution

//! and authorization) and routing to [`Server::handle`]; `router` is the

//! standalone server built on [`DirBackend`].

use axum::http::{header, HeaderMap, Method, StatusCode};

use axum::routing::any;

/// Which kind of access a request needs (spec §15.1: reads may be open;

/// a push must be authenticated when any credential is configured).

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

pub enum Access {

    Read,

    Push,

}

/// What a host provides to the protocol server: how a repository name maps

/// to a repository on disk and who may do what. `oxy serve` uses

/// [`DirBackend`]; a hub supplies its own with accounts and roles.

pub trait Backend: Send + Sync + 'static {

    /// Open the repository called `name`, or fail with the status to

    /// answer. An unknown name is `404`; a name the caller may not see

    /// SHOULD also be `404`, so private repositories are not enumerable.

    fn open(&self, name: &str) -> Result<Repo, Failure>;

    /// Decide whether this request may perform `access` on `name`.

    fn authorize(&self, name: &str, access: Access, headers: &HeaderMap) -> Result<(), Failure>;

    /// Called after a push was processed, with its per-reference results

    /// (accepted or refused), for logs and cache invalidation.

    fn after_push(&self, _name: &str, _results: &[oxy_core::protocol::RefResult]) {}

}

/// A protocol server over any [`Backend`], serialising the pushes to each

/// repository. Hosts route requests to [`Server::handle`].

pub struct Server {

    backend: Box<dyn Backend>,

/// An error response: a status and a plain-text body.

#[derive(Debug)]

pub struct Failure(pub StatusCode, pub String);

/// The wire protocol's endpoints (spec §16.1), named as in the URL.

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

pub enum Endpoint {

    Capabilities,

    Refs,

    Negotiate,

    Fetch,

    Objects,

    Checkpoint,

    Shallow,

    Push,

}

impl Endpoint {

    pub fn parse(name: &str) -> Option<Endpoint> {

        Some(match name {

            "capabilities" => Endpoint::Capabilities,

            "refs" => Endpoint::Refs,

            "negotiate" => Endpoint::Negotiate,

            "fetch" => Endpoint::Fetch,

            "objects" => Endpoint::Objects,

            "checkpoint" => Endpoint::Checkpoint,

            "shallow" => Endpoint::Shallow,

            "push" => Endpoint::Push,

            _ => return None,

        })

    }

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

        match self {

            Endpoint::Capabilities => "capabilities",

            Endpoint::Refs => "refs",

            Endpoint::Negotiate => "negotiate",

            Endpoint::Fetch => "fetch",

            Endpoint::Objects => "objects",

            Endpoint::Checkpoint => "checkpoint",

            Endpoint::Shallow => "shallow",

            Endpoint::Push => "push",

        }

    }

    /// The HTTP method the endpoint answers to.

    pub fn method(self) -> Method {

        match self {

            Endpoint::Capabilities | Endpoint::Refs => Method::GET,

            _ => Method::POST,

        }

    }

    fn access(self) -> Access {

        match self {

            Endpoint::Push => Access::Push,

            _ => Access::Read,

        }

    }

}

pub fn valid_repo_name(name: &str) -> bool {

impl Server {

    pub fn new(backend: impl Backend) -> Arc<Server> {

        Arc::new(Server { backend: Box::new(backend), locks: Mutex::new(HashMap::new()) })

    }

    pub fn backend(&self) -> &dyn Backend {

        self.backend.as_ref()

    }

    fn lock_for(&self, name: &str) -> Arc<Mutex<()>> {

        self.locks.lock().unwrap().entry(name.to_string()).or_default().clone()

    }

    /// Answer one protocol request for repository `name`. `method` is

    /// checked against the endpoint; the body is the raw CBOR request.

    pub async fn handle(self: &Arc<Self>, name: String, endpoint: Endpoint, method: &Method, headers: &HeaderMap, body: Bytes) -> Response {

        if *method != endpoint.method() {

            return Failure(StatusCode::METHOD_NOT_ALLOWED, format!("{} is {}", endpoint.name(), endpoint.method())).into_response();

        }

        if let Err(f) = self.backend.authorize(&name, endpoint.access(), headers) {

            return f.into_response();

        }

        let server = Arc::clone(self);

        let result = tokio::task::spawn_blocking(move || server.respond(&name, endpoint, body)).await;

        match result {

            Ok(Ok(r)) => r,

            Ok(Err(f)) => f.into_response(),

            Err(e) => Failure(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()).into_response(),

        }

    }

    fn respond(&self, name: &str, endpoint: Endpoint, body: Bytes) -> Result<Response, Failure> {

        let r = self.backend.open(name)?;

        Ok(match endpoint {

            Endpoint::Capabilities => ok(wire::encode_capabilities(r.id()?)),

            Endpoint::Refs => ok(wire::encode_refs(r.id()?, &r.remote_refs()?)),

            Endpoint::Negotiate => {

                let (have, want) = wire::decode_negotiate(&body)?;

                ok(wire::encode_hashes(&r.negotiate(&have, &want)?))

            }

            Endpoint::Fetch => {

                let (changes, max_blob) = wire::decode_fetch(&body)?;

                ok(wire::encode_bundle(&r.bundle_for_filtered(&changes, max_blob)?))

            }

            Endpoint::Objects => {

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

                let bundle = oxy_core::protocol::Bundle { objects: r.objects_for(&refs)?, ..Default::default() };

                ok(wire::encode_bundle(&bundle))

            }

            Endpoint::Checkpoint => {

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

                let lock = self.lock_for(name);

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

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

            }

            Endpoint::Shallow => {

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

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

            }

            Endpoint::Push => {

                let (bundle, updates, policy, tags) = wire::decode_push(&body)?;

                let lock = self.lock_for(name);

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

                let results = r.receive_push(bundle, updates, policy, tags)?;

                self.backend.after_push(name, &results);

                ok(wire::encode_push_response(&results))

            }

        })

    }

}

/// The backend of `oxy serve`: one repository per subdirectory of a root,

/// open reads, and pushes gated by a list of bearer tokens.

pub struct DirBackend {

    pub root: PathBuf,

    pub tokens: Vec<String>,

}

impl Backend for DirBackend {

        let dir = self.root.join(name);

    fn authorize(&self, _name: &str, access: Access, headers: &HeaderMap) -> Result<(), Failure> {

        if access == Access::Read || self.tokens.is_empty() {

        match bearer_token(headers) {

            Some(t) if self.tokens.iter().any(|x| x == t) => Ok(()),

/// The token of an `Authorization: Bearer` header, if any.

pub fn bearer_token(headers: &HeaderMap) -> Option<&str> {

    headers.get(header::AUTHORIZATION).and_then(|v| v.to_str().ok()).and_then(|v| v.strip_prefix("Bearer ")).map(str::trim)

async fn dispatch(State(server): State<Arc<Server>>, Path((repo, endpoint)): Path<(String, String)>, method: Method, headers: HeaderMap, body: Bytes) -> Response {

    match Endpoint::parse(&endpoint) {

        Some(e) => server.handle(repo, e, &method, &headers, body).await,

        None => Failure(StatusCode::NOT_FOUND, "no such endpoint".into()).into_response(),

    }

/// The router of `oxy serve`: `/{repo}/oxy/v1/{endpoint}` over a [`DirBackend`].

    let server = Server::new(DirBackend { root: cfg.root, tokens: cfg.tokens });

    Router::new().route("/{repo}/oxy/v1/{endpoint}", any(dispatch)).with_state(server)

#[test]

fn a_bare_repository_is_served_and_browsed_without_a_working_copy() {

    hermetic();

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

    let root = dir.path();

    let served = root.join("served");

    let hosted = Repo::init_bare(&served.join("lib")).unwrap();

    assert!(hosted.is_bare());

    assert!(hosted.working_copy().is_err(), "a bare repository has no working copy");

    assert!(!served.join("lib").join(".oxy").join("workspace").exists());

    let base = start(&served, vec![]);

    let url = format!("{base}/lib");

    // A client clones the empty repository, commits twice, and pushes.

    let work = root.join("work");

    let client = Repo::clone(&url, &work).unwrap();

    write(&work, "src/lib.rs", b"pub fn one() {}\n");

    client.snapshot("test").unwrap();

    let c1 = client.commit("one", &[]).unwrap();

    write(&work, "src/lib.rs", b"pub fn one() {}\npub fn two() {}\n");

    client.snapshot("test").unwrap();

    let c2 = client.commit("two", &[]).unwrap();

    let results = client.push("origin", false).unwrap();

    assert!(results.iter().all(|r| r.ok), "{results:?}");

    // The host reads history, files and blame from the bookmark's state alone.

    let hosted = Repo::open(&served.join("lib")).unwrap();

    assert!(hosted.is_bare());

    let heads = hosted.bookmark_heads().unwrap();

    assert_eq!(heads, vec![c2]);

    let log = hosted.log().unwrap();

    assert_eq!(log.iter().map(|e| e.hash).collect::<Vec<_>>(), vec![c2, c1]);

    assert!(log.iter().all(|e| !e.is_working_copy));

    assert_eq!(hosted.log_state(&[c1]).unwrap().len(), 1);

    assert_eq!(hosted.file_at("src/lib.rs", Some(&heads)).unwrap(), b"pub fn one() {}\npub fn two() {}\n");

    let blame = hosted.blame_in("src/lib.rs", &heads).unwrap();

    assert_eq!(blame.iter().map(|l| l.hash).collect::<Vec<_>>(), vec![c1, c2]);

    assert_eq!(hosted.log_for_path("src/lib.rs").unwrap().len(), 2);

    assert_eq!(hosted.diff_files(Some(&c2)).unwrap().len(), 1);

    assert!(matches!(hosted.verify_change(&c2).unwrap(), SignatureStatus::Unsigned | SignatureStatus::Valid { .. }));

    // Snapshotting a bare repository is refused rather than inventing a working copy.

    assert!(hosted.snapshot("test").is_err());

}

/// A host embeds the protocol with its own backend: names with an owner

/// segment, reads gated per repository, and a push hook.

#[test]

fn a_custom_backend_embeds_the_protocol() {

    use axum::extract::{Path as AxPath, State};

    use axum::http::{HeaderMap, Method, StatusCode};

    use axum::response::{IntoResponse, Response};

    use oxy_server::{Access, Backend, Endpoint, Failure, Server};

    use std::sync::{Arc, Mutex};

    struct Hub {

        root: std::path::PathBuf,

        pushes: Arc<Mutex<Vec<String>>>,

    }

    impl Backend for Hub {

        fn open(&self, name: &str) -> Result<Repo, Failure> {

            let Some((owner, repo)) = name.split_once('/') else { return Err(Failure(StatusCode::NOT_FOUND, "no such repository".into())) };

            let dir = self.root.join(owner).join(repo);

            if !dir.join(".oxy").is_dir() {

                return Err(Failure(StatusCode::NOT_FOUND, "no such repository".into()));

            }

            Repo::open(&dir).map_err(|e| Failure(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))

        }

        fn authorize(&self, name: &str, access: Access, headers: &HeaderMap) -> Result<(), Failure> {

            // `secret/*` is private: unknown to anyone without the token, even for reads.

            let token = oxy_server::bearer_token(headers);

            if name.starts_with("secret/") && token != Some("s3cret") {

                return Err(Failure(StatusCode::NOT_FOUND, "no such repository".into()));

            }

            if access == Access::Push && token.is_none() {

                return Err(Failure(StatusCode::UNAUTHORIZED, "sign in to push".into()));

            }

            Ok(())

        }

        fn after_push(&self, name: &str, results: &[oxy_core::protocol::RefResult]) {

            self.pushes.lock().unwrap().push(format!("{name}: {}", results.iter().filter(|r| r.ok).count()));

        }

    }

    async fn route(State(server): State<Arc<Server>>, AxPath((owner, repo, endpoint)): AxPath<(String, String, String)>, method: Method, headers: HeaderMap, body: axum::body::Bytes) -> Response {

        match Endpoint::parse(&endpoint) {

            Some(e) => server.handle(format!("{owner}/{repo}"), e, &method, &headers, body).await,

            None => Failure(StatusCode::NOT_FOUND, "no such endpoint".into()).into_response(),

        }

    }

    hermetic();

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

    let root = dir.path();

    Repo::init_bare(&root.join("repos/andy/app")).unwrap();

    Repo::init_bare(&root.join("repos/secret/plans")).unwrap();

    let pushes = Arc::new(Mutex::new(Vec::new()));

    let server = Server::new(Hub { root: root.join("repos"), pushes: pushes.clone() });

    let listener = TcpListener::bind("127.0.0.1:0").unwrap();

    let port = listener.local_addr().unwrap().port();

    std::thread::spawn(move || {

        let rt = tokio::runtime::Builder::new_multi_thread().enable_all().build().unwrap();

        rt.block_on(async move {

            listener.set_nonblocking(true).unwrap();

            let app = axum::Router::new().route("/{owner}/{repo}/oxy/v1/{endpoint}", axum::routing::any(route)).with_state(server);

            axum::serve(tokio::net::TcpListener::from_std(listener).unwrap(), app).await.unwrap();

        });

    });

    std::thread::sleep(std::time::Duration::from_millis(50));

    let base = format!("http://127.0.0.1:{port}");

    // Anonymous clone of the public repository works; the private one does not exist for outsiders.

    let work = root.join("work");

    let client = Repo::clone(&format!("{base}/andy/app"), &work).unwrap();

    assert!(Repo::clone(&format!("{base}/secret/plans"), &root.join("nope")).is_err());

    // A push needs a token; with one it lands and the hook sees it.

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

    client.snapshot("test").unwrap();

    client.commit("a", &[]).unwrap();

    assert!(client.push("origin", false).is_err(), "anonymous push must be refused");

    let mut client = client;

    client.config.set("remote.origin.token", "s3cret").unwrap();

    let results = client.push("origin", false).unwrap();

    assert!(results.iter().all(|r| r.ok), "{results:?}");

    assert_eq!(pushes.lock().unwrap().as_slice(), ["andy/app: 1"]);

    let hosted = Repo::open(&root.join("repos/andy/app")).unwrap();

    assert_eq!(hosted.bookmark_heads().unwrap().len(), 1);

}

## Phase 4 (2026-09-27): what Oxygenhub needs (oxygenhub/docs/spec.md section 18)

- [x] Bare repositories: `Repo::init_bare`, `is_bare`, `oxy init --bare`; `working_copy` refuses; `log`, `log_for_path` work from the bookmark state; `log_state`, `blame_in`, `log_for_path_in` for any state.

- [x] Embeddable server: `oxy_server::{Backend, Server, Endpoint, Access, Failure, DirBackend, bearer_token}`; `router` is `DirBackend` on `/{repo}/oxy/v1/{endpoint}`; `after_push` hook.

- [ ] `oxy identity sign-challenge` and `verify_challenge` (hub 0.2).

- [ ] `oxy seal <hash>..` and `--proposal URL` (hub 0.3).

- [ ] `oxy proposal show|land URL` (hub 0.3).

- [ ] Delegate-signed changes from an edit set without a workspace (hub 0.6).

- [ ] `Repo::log_window` and a shared `graph::layout` (hub 0.1 uses `log_state` and its own layout until then).

- [ ] `receive_push` reporting old/new state and new changes per reference (hub 0.2 pushes log).

Embedding: `oxy_server::Server` answers any endpoint for a repository name

a host's `Backend` resolves and authorises (`open`, `authorize`, and an

`after_push` hook), so a hub with `owner/name` paths and its own accounts

routes `/{owner}/{name}/oxy/v1/{endpoint}` to `Server::handle`; `oxy serve`

is `DirBackend` on that same server.

| **Status** | Draft 0.8c |

A repository has one or more workspaces, each with a `WorkspaceId` (128-bit random) and a checkout directory. Each workspace has exactly one **working-copy change** at any time. The primary workspace is the directory holding `.oxy/`; a secondary workspace holds a `.oxy` file instead, `oxydir: <path>` and `workspace: <id>`, pointing at the shared repository, and the repository records each workspace's directory under `.oxy/workspaces/<id>/`. `oxy workspace add PATH [CHANGE..]` creates one, `list` shows them, and `forget` drops one from the view without touching its files. Workspaces do not nest. A **bare** repository (`oxy init --bare`, marker `.oxy/bare`) has no workspace and no working-copy change; it holds objects, the operation log and references only, for hosting. Working-copy commands fail on it with a clear message; every state-based query works.

oxy init [PATH] [--bare]            oxy clone URL [--sparse PATH].. [--depth N] [--max-blob SIZE]

*Changelog.* Draft 0.8c (2026-09-27): bare repositories (`oxy init --bare`, §12.2: no workspace, no working copy; hosting) and the reference server as an embeddable library (§15.1). Draft 0.8b (2026-09-27): the machine interface for editors (§24): `root`, `cat`, `version`, `hunks`, `discard`, and `--json` on the reporting commands.

    Init {

        path: Option<PathBuf>,

        /// No working copy: an object store and references only, for hosting

        #[arg(long)]

        bare: bool,

    },

        Cmd::Init { path, bare } => workspace::init(path, bare),

pub fn init(path: Option<PathBuf>, bare: bool) -> Result<i32> {

    let repo = if bare { Repo::init_bare(&path)? } else { Repo::init(&path)? };

    println!("{} {}oxy repository in {}", ui::done("Initialized"), if bare { "bare " } else { "" }, ui::path(repo.root().display()));