Compare main … paths-for-resolutions-and-amend

# The CI profile (oxygen#139): every test runs, and a JUnit report is

# written to target/nextest/ci/junit.xml for the hub's test report

# (the job's `junit` artifact).

[profile.ci]

fail-fast = false

[profile.ci.junit]

path = "junit.xml"

// 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"

}

    rootfs "cas://blob/836461b613019f62399a960c61a25c482eb74e30054ff2cd44d5594c3305872b"

    rootfs "cas://blob/836461b613019f62399a960c61a25c482eb74e30054ff2cd44d5594c3305872b"

// The riscv64 build image on narvi-1 (oxygenflow#69): Ubuntu 24.04 riscv64

// with Rust 1.97.1 and the same vendored crates, in the syscall tier (the

// board has no hardware virtualisation, so no microVM). `runs-on` keeps it

// on a RISC-V runner.

sandbox "rust-riscv64" {

    runtime "syscall"

    rootfs "cas://blob/b4edba9173ddf63aa1df46222e6a59b265071b19f2815c89d0153b593835c616"

    runs-on "riscv64"

    memory-limit "4GiB"

    cpu-limit 6

    network "loopback"

    env {

        CARGO_INCREMENTAL "0"

        CARGO_PROFILE_RELEASE_DEBUG "0"

        CARGO_BUILD_JOBS "4"

    }

}

// The tests, run under cargo-nextest and cargo-llvm-cov: a test report

// (JUnit, kept whether or not they pass; #139) for the hub's Tests tab and

// line coverage (LCOV, oxygenhub#113) for its Coverage tab, from one run.

    exec "cargo" "llvm-cov" "nextest" "--workspace" "--locked" "--profile" "ci" "--lcov" "--output-path" "/src/target/lcov.info"

        artifact "junit" {

            path "/src/target/nextest/ci/junit.xml"

            when "always"

        }

        artifact "oxy-src.tar.gz" {

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

        }

        }

    }

}

// The native RISC-V check (oxygenflow#69): oxy built and used on narvi-1,

// a real riscv64 board, so each release is known to run there and not

// only to cross-compile (dist). Like dist, a push runs it only when it

// touches these paths; "Run pipeline" and reruns always do. Its target

// directory is cached between passing runs (oxygenflow#70).

job "riscv64" {

    sandbox "rust-riscv64"

    depends-on "fmt"

    scope "Cargo.toml" "scripts/dist.sh" "packaging/**" ".flow/riscv64-check.sh"

    timeout "3h"

    mount {

        source "ephemeral://disk"

        target "/src/target"

        size "16GiB"

        // Kept from this job's last passing run in the syscall tier too

        // (oxygenflow#70): the first build is cold (~40 min on narvi-1),

        // later ones build only what changed.

        cache "target"

        key "Cargo.lock"

    }

    exec "sh" ".flow/riscv64-check.sh"

    output {

        artifact "oxy-linux-riscv64-native" {

            path "/src/target/release/oxy"

#!/bin/sh

# The native RISC-V check (oxygenflow#69): on narvi-1, a riscv64 board,

# build oxy natively and use it, so a release is known to work on real

# RISC-V hardware, not only to cross-compile for it (dist does that).

set -eu

uname -m

cargo build --release --locked -p oxy

oxy=/src/target/release/oxy

"$oxy" --version

# A repository's life in miniature: an identity, a signed change, a

# bookmark, a merge, and a full integrity check.

export OXY_HOME="$(mktemp -d)"

cd "$(mktemp -d)"

"$oxy" --plain init

"$oxy" --plain identity create --name "narvi-1 check" --email [email protected]

"$oxy" --plain config --user core.sign change

echo one > a.txt

"$oxy" --plain commit -m "first"

"$oxy" --plain bookmark create side

"$oxy" --plain bookmark switch side

echo two > b.txt

"$oxy" --plain commit -m "second, on side"

"$oxy" --plain bookmark switch main

"$oxy" --plain merge side

"$oxy" --plain log

"$oxy" --plain verify

"$oxy" --plain fsck

test -f b.txt

echo "oxy works natively on $(uname -m)"

# oxygen#145: two changes adding changelog entries keep both.

CHANGELOG.md merge=union

## 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 server can add a note to a reference a push moved (#148).** `oxy-server`'s `Backend` has a `push_notes` step: each note is added to that accepted reference's result, which `oxy push` shows in place of "updated". OxygenHub will use it to say when a push moves the bookmark of a proposal that has already landed (oxygenhub#329).

- **Identical sides settle by themselves (#146).** Two bookmarks that each resolved the same conflict to the same text conflicted again when merged, both sides the identical lines. A conflict whose sides are byte-identical now settles as `merge=union` adjacent insertions do (#145), in any file and keeping one side: a checkout writes it once ("kept one of its identical sides") and the next commit records the resolution, and a host landing a proposal settles it too.

- **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.

- **A shallow clone fetches its checkpoint in parts (#137).** The checkpoint of a big state came as one answer, the whole state's graph blobs in one body (about 2 GB for the VS Code history), built and held whole on both sides. A server now answers `checkpoint-index` (the checkpoint and its history, no graphs), and the client fetches the graph blobs it lacks with `objects`, 2,048 at a time; `objects` reads them in pack order. An older server answers 404 and gets the one-piece request as before.

- **A keyless agent follows its owner's newest identity (#82).** Every delegation rotates its owner's identity, so the `author.key` an agent's home was given goes stale, and its changes named an identity two rotations old (verifying only because a grant from before a rotation still counts). With `author.for = ACCOUNT` in the home, the hub sends the account's newest linked identity with each certificate, with its chain back to the grant's key; oxy keeps it in the home (`keys/author.for`), stores the chain beside the change so the grant checks, and authors as it from then on. A repository's own `author.key` pin still wins.

- **Changelogs stop conflicting (#145).** A file marked `merge=union` in `.oxyattributes` (`CHANGELOG.md merge=union`) has its adjacent insertions settled by the checkout itself: both sides kept, the earlier change's first, as `oxy resolve --both` does, and the next commit records the resolution. Only adjacent insertions: where two changes changed the same lines, the markers stay. Oxygen's own changelog is marked so.

- **Two changes adding lines at the same place are settled with one command (#121).** Like Git, oxy leaves a conflict when two changes each add lines after the same line, since either order can be wrong for code; settling it meant editing out the markers by hand. `oxy resolve --both [PATH]…` now keeps every side of each such *adjacent insertion*, the earlier change's first (`--reverse` for the other order), and `oxy status` says which conflicts qualify. It leaves the markers where the sides changed the same lines (keeping both would keep two versions of them) or where the lines between the markers were edited. Conflict markers now list their sides earliest change first, not in hash order.

## 0.7.0 (2026-10-26)

- **Many objects are read in pack order (#137):** `Store::get_many` (a clone's checkpoint, a fetch's objects) reads packed objects by pack and offset, each thread a run of them, so a spinning disk sweeps instead of seeking across the packs; results keep the asked order. The server's gathering of a VS Code-sized checkpoint (tens of thousands of objects in ~95 packs) was the slow part of a depth-0 clone on Earth.

- **Windows paths print plainly (#143):** a repository's root showed as `\\?\C:\work\demo` in every message, Windows' verbatim form from `canonicalize`; oxy now drops the prefix where the plain path says the same (`oxy_core::portable::canonical`). Found running the shipped Windows build on a Windows 11 VM.

- **Oxygen's CI writes a test report beside its coverage (#139):** the test job runs under cargo-nextest (`.config/nextest.toml`, profile `ci`) as well as cargo-llvm-cov, keeping a JUnit report whether or not the tests pass, for the hub's Tests tab.

- **Pushing a new bookmark sends only what the remote lacks (#142).** A push was worked out against the remote's heads for that bookmark alone, so a bookmark new to the remote sent its whole history again: slow on a big repository, and OxygenHub's push protection scanned all of it (and refused a proposal's bookmark for an example key in a change main had had for weeks). The heads of every bookmark the remote lists now count as already there.

- **A binary file's or subrepo pin's conflict can be settled from the command line (#140).** Two changes that replaced the same binary file, or moved the same subrepo pin, leave a replace conflict with no markers to edit, and every commit was refused until it was settled, which only a hosted edit could do. `oxy resolve PATH…` now settles it with what the working copy holds at the path (the file, or the subrepo's pin): the next commit is a resolution replacing every version with it. A path with no replace conflict is refused, and a choice is forgotten once committed.

- **The object store works where hard links are refused (#141).** Android forbids apps hard links in their own storage, so the OxygenHub app's phone runner could clone nothing (`Permission denied`). Where a link is refused, objects are renamed into place with `renameat2(RENAME_NOREPLACE)`: as atomic, and still never over a name that is taken.

- **Rendering a big tree is many times faster, and clone, pull, switch and `oxy workspace add` stop rendering it twice (#137).** Measured on the VS Code history's depth-0 clone (19,545 files, 166,425 changes), `oxy workspace add` took 467 s on Earth and 176 s on an 8-core workstation, 11 GB at its peak; it now takes 7.5 s and 1.8 GB on the workstation. Three causes: (1) whether one change depends on another, which rendering asks about every deleted line, was answered by a depth-first walk that compared a change with the one sought only on coming back up to it, so it went through thousands of changes first although the answer is nearly always a direct dependency (spec §8.1): 262,678 questions took 4.4 billion steps and 838 CPU-seconds, and now take 5 CPU-seconds, with the same answers; (2) finding the subrepos rendered every file of the tree, after every clone, pull, switch and `workspace add`, where reading the tree and the subrepos' pins is enough; (3) a new workspace started on the target state with an empty directory, so the checkout's first snapshot found the whole tree deleted and rendered it to say so. `OXY_TIMINGS=1` now also says how a checkout's files were ordered (`graph: single order`…) and how its blobs were read.

- **`oxy serve` takes a push of more than 2 MB (#138).** It set no request limit of its own, so axum's default of 2 MB applied, and a larger push part was cut off with `Broken pipe` at the client and nothing in the server's log. It now takes up to 4 GiB a request (`oxy_server::BODY_LIMIT`), OxygenHub's default `push_body_limit`; OxygenHub was not affected.

- **A push no longer sends a replaced or removed binary file's old content again (#136).** A bundle carried both the old and the new blob of every binary file a change replaces, so a change removing ~1,100 tracked cache files (oxygenhub-android's set-up) pushed all of them again, over 100 MB, though the hub stored each when it was added. The old blob is always the new blob of a change the replacement depends on, which the receiver already holds or which the same bundle carries, so pushes and fetch answers now carry only the new one.

## 0.6.0 (2026-10-25)

- **A shallow clone of a big repository works, and quickly (#137).** `oxy clone --depth 0` of the VS Code history failed after eleven minutes ("object … not found"): the blobs of the state's binary files are named only by the changes that set them, which a depth-0 clone does not take, so nothing brought them. They are now fetched with the checkpoint (in parts), or left to be fetched on read under `--max-blob`. The checkpoint itself was stored object by object, each written loose and flushed (57,498 objects at 27 a second); it is now stored in one batch, as a fetch's objects are.

- **A checkpoint is served faster, and says where its time goes (#137).** A server gathered a checkpoint's graph blobs and their chunks one read at a time: six minutes for the VS Code state's 57,000. They are now read in two parallel batches. `OXY_TIMINGS=1` now times the checkpoint's phases on both sides (`checkpoint: gather its objects`, `serve: encode the checkpoint`, `remote: checkpoint answer`, `shallow: store the checkpoint` and the rest).

- **A depth-0 clone takes no change (#137).** `oxy clone --depth 0` took the head changes themselves (the VS Code import's main has 33,835 heads), though the checkpoint already holds every change's metadata, so depth 0 now takes none (spec §17's "a checkpoint plus zero history"): its heads become the shallow boundary, and commit, push and pull on top work as before (a shallow repository takes and builds on changes below what it cloned, which the remote holds).

- **A push no longer passes a proxy's request limit (#133).** A push to a hub behind Cloudflare, which takes at most 100 MB in one request, was refused `HTTP 413` with Cloudflare's HTML page printed raw: parts of a long push were about 256 MiB, and one change's blobs went in one request however many there were. Parts are now about 64 MiB (`push.batch-bytes`), a part whose blobs pass that sends them first in parts of objects alone, an HTML error page is shown by its title, and a 413 says how to push in smaller parts.

- **A keyless agent's grant survives its owner's key rotation (#135).** Every delegation an owner adds or removes renews their identity, and a repository that names the newest key as `author.key` read every change their agent sealed as INVALID ("key … is neither the author nor a delegate"), and its pushes were refused, because the agent's grant was signed by the owner's earlier key. A grant by a key the author's identity was rotated or renewed from now counts when it was made before that rotation; one an old key made after it does not.

- **A tag can be withdrawn, by a signed withdrawal (oxygenhub#301).** There was no way to remove a tag anywhere: a mistaken release tag stayed for good. `oxy tag delete NAME [-r REASON]` records an `untag` attestation naming the tag's state, signed like a tag (a ten-minute keyless key too), and the next `oxy push` sends it to a remote that still has the tag; `oxy push --delete tags/NAME` does both at once. A receiver under a policy accepts it only from a key that may create the tag, keeps it beside the tag's creation, and lists withdrawn tags in its refs answer (key 8), so a `fetch` withdraws the tag there too (`tag v1 was withdrawn on origin, and here`). A withdrawn name is never used again, so a tag name never names two states. `oxy-server`'s `Backend` gains `vet_tag_withdrawal` (OxygenHub refuses while a release uses the tag), and `Repo::host_tag_create` and `host_tag_withdrawal` let a host make or withdraw a tag for a signed-in user. The wire change is additive, but an older server refuses a withdrawal (wrong attestation kind), and an older client keeps a withdrawn tag.

- **A keyless agent's changes verify in a repository that has never seen its owner (#134).** An agent's ten-minute key is certified under its owner's signed grant, and a change it signed only verified where the owner's identity was already stored: in a new repository, or one the owner had not pushed to since a key rotation, `oxy log --verify` and the hub said INVALID ("grant is by an unknown author"). OxygenHub now sends the grant's signer with the certificate (`grantor_identity`, additive), `oxy` keeps it (else uses `<oxy home>/keys/<key>.identity`, or refuses with how to put it there), and a push brings it beside the certificate, so the receiver can check the grant.

## 0.5.1 (2026-10-20)

- **oxy 0.5.0 and older can clone a repository again after a keyless agent tagged it (#131).** Since #129 a release tag may be signed by a ten-minute certified key, which released clients do not know how to authorize: they refused the tag (`key … may not create tags/v0.5.0 under this repository's policy`), and with it the whole clone, fetch or `oxy submodule update`. Clients now send `User-Agent: oxy/<version>` and declare what they understand in `Oxy-Features` (`certified-tags` so far; docs/protocol.md, *Client capabilities*). Under a policy, a server leaves out of its refs answer to a client that does not declare `certified-tags` every tag that only a certificate authorizes, so that client clones the rest as if the tag did not exist. The rule is `Repo::refs_for_client` in oxy-core; `oxy-server` gains a `Backend::adjust_refs` hook, given the request headers, whose default applies it, so `oxy serve` and every embedding host do.

- **Keyless agents can create release tags (#129).** `oxy tag create` and `oxy push` under a keyless home was refused "unknown key": the push did not carry the tag signer's identity and certificate, and tags were authorized only by keys the policy names, never by a certificate under a subject grant. The push now carries them, and a receiver authorizes a short-lived key's tag by a subject grant at its own clock, as it does a bookmark move, and records when it accepted it (OxygenHub signs that with its key). A fetch checks such a tag at that acceptance, or at its integrated time when the hub's log gives one, so a release tag made with a ten-minute key is still fetched months later. A fetch never checks it at the time the tag claims: without an acceptance the tag is left out with a warning (`tags/NAME not updated`), and the rest is fetched. A client keeps the acceptance and serves and pushes it with the tag, so a tag passed on to another remote, or cloned from a clone, keeps its time. The wire change is additive: tags in `refs` and `push` gain keys 4 to 6 (acceptance, log place, cosigned checkpoints), which older readers ignore.

## 0.5.0 (2026-10-20)

- **A repository kept in a bucket finds signatures and seals without a LIST each (#116).** Every lookup of an object's signatures, seals, receipts, approvals or certificate listed a prefix in the bucket, and most of these lookups found nothing. Writers now also add each such entry to a journal (`pack-entries`, updated by compare-and-swap), and `oxy gc` folds them all into one list. Once a store has been folded, a reader reads the lists and the journal when it opens it, and again after 30 seconds (as long as the pack listing is kept), and looks everything up from them. Another writer's entry is seen within 30 seconds, as its pack would be, even by a handle a server keeps open. The first `oxy gc` also copies the one-list keys of much older stores (`sigs/`, `seals/`, `certs/`, …) into the current layout and marks them folded, so readers stop requesting them; until now nearly every lookup made one of these requests and found nothing. On the test store, 40 lookups went from 85 requests (40 LISTs) to 7 (one journal read and no LIST). Older readers are unaffected, because every entry still has its own key. Entries written by oxy 0.4.6 or older after the fold are missed until the next `oxy gc`, so upgrade every client that writes to the bucket first, then run `oxy gc` once. A server's `/health` counts journal reads as `read_journal`. A repository's own directory works as before.

- **A server can refuse a push by what it adds (oxygenhub#268).** `oxy-server`'s `Backend` has a `vet_push` step, called with the push's changes before anything is stored or moved; OxygenHub uses it for push protection (secret scanning). The refusal reaches `oxy push` as the server's own text, several lines included, and a refusal that mentions a certificate or a timeout no longer picks up a misleading hint.

- **Fetch checks the hub's transparency log (oxygenhub#238).** A hub that keeps a log sends its latest checkpoint with every refs answer, and each bookmark's attestation with its log entry and inclusion proof. The first fetch pins the hub's log key in `<oxy home>/tlog/<hub>` with the last checkpoint seen. A later checkpoint must be signed by that key and extend the last one: a smaller log, another root at the same size or a failed consistency proof fails the fetch, saying the hub showed two histories. An attestation not logged yet, or not proved, is only a note for now, printed by `fetch` and `pull` and in `--json`. A hub that comes back with a new log key (a new key, a reused address, a rename) is a loud note, and the new key is pinned. Older hubs and clients ignore the new fields.

- **`oxy tlog verify` audits a hub's whole log (oxygenhub#238).** It accepts the hub's checkpoint by the same rules as fetch, downloads every entry and requires them to make the root the checkpoint signs, then lists this repository's entries, a key's (`--key`) or all of them (`--all`); `--json` too. It also shows which witnesses cosigned and when.

- **Trusted time from witnesses (oxygenhub#240).** An entry's integrated time is the earliest time a trusted witness cosigned a checkpoint that holds it, by the witness's clock, so a hub can only make it later, never earlier. A fetch pins the hub's witnesses beside its log key (`<oxy home>/tlog/<hub>.witnesses`; a new or changed witness key is a note), counts a cosignature only when it verifies against a pinned key, and checks a delegate's delegation and a short-lived key's certificate at that time. Without one it checks them as before, at the hub's acceptance or the attestation's own time. A claimed time more than 10 minutes off the integrated time is noted, not refused, for now. The wire change is additive.

- **`oxy witness serve`: a witness anyone can run (oxygenhub#238).** `oxy witness serve --name HOST --log ORIGIN=FILE …` serves the C2SP tlog-witness `add-checkpoint` call. It cosigns, with this oxy home's key and its own clock, each checkpoint that verifies with the log's key and extends the last one it cosigned, and refuses a fork. What it cosigned is kept per log in `--state`, so it survives a restart.

- **`oxy show --stat` (#119).** Lists the files a change touched instead of its diff: each path with lines added and removed and its kind, renames as from → to, and a total. `--json` gives each file's counts.

- **`oxy merge` takes a remote's bookmark (#117).** `oxy merge oxygenhub/develop` said "no bookmark": merge looked only at local bookmarks, so merging what a remote has meant switching to it, pulling and switching back. It now takes a remote's tracking bookmark as last fetched, as revsets do, and says where it looked when neither exists.

- **Commit a resolution by paths, and amend only some paths (#118).** A conflict resolution can be committed by paths, leaving other work uncommitted on top of the resolved state, as long as the paths include every file it resolves, whole; otherwise the refusal names them. `oxy amend PATH…` folds only those paths into the head and leaves the rest uncommitted.

- **`oxy doctor` checks the trust policy (#127).** A repository with no policy was "Everything looks right" while every fetch warned that nothing was verified. Doctor now has a trust line: no policy is a warning that says who sets one and how; a policy shows its serial, roots, rules and expiry, warns within 30 days of expiry and fails once it has expired.

- **The same file added on both sides is one file (#101).** The same path added on two bookmarks with identical content (files, symlinks, or subrepos at the same pin) now merges with no conflict and nothing to resolve. Every peer and the hub show it the same way whatever order the changes came in, and it stays one file through later edits, moves, removals and partial commits. Different content or a different mode is still a name conflict, and directories are not unified. The stored and signed formats are unchanged.

- **A bookmark nobody can verify no longer breaks every fetch (oxygenhub#266, oxygenhub#271).** A delegate or short-lived key that moved a bookmark without signing any of its changes left every client failing the whole fetch with "unknown key". A fetch now carries the identities and certificates of the keys that signed every bookmark's latest attestation and every tag's, so clients, older ones included, can verify the move. A client that still cannot verify a bookmark other than the current one leaves that bookmark as it was, warns naming it and why, and fetches the rest. The current bookmark (the one a pull takes or a clone checks out) still fails, as does a missing, unauthorised or rolled-back attestation. The signers are gathered once per operation, not on every fetch call: a repository in a bucket with 145 bookmarks had taken 14 s a fetch.

- **Readers never wait for a push or gc (oxygenhub#249).** A repository can now be read safely while another process writes it. A handle reads the operation head once and keeps it, so one request never mixes two views. A read that misses reloads the pack list and tries once more. A repack retires the packs and loose objects it replaces instead of deleting them, and `gc` deletes them only an hour later; `oxy gc` says what it deleted or kept for readers. A forge no longer needs to hold readers back while it pushes or collects garbage.

- **A repository kept in a bucket lists its packs less often (#116).** Every open listed the bucket's packs, and a forge opens the store once per request. The pack listing is now kept for 30 seconds and forgotten the moment this process writes or deletes a pack, so its own packs are never hidden; another writer's new pack is seen within 30 seconds. Opening a store no longer sends a request per pack, and a bucket store's stat is a HEAD of the key, not a listing. A server's `/health` counts pack listings, kept listings and other listings apart.

- **Text that looks like a conflict marker no longer blocks a resolution (#126).** A file that showed oxy's own conflict markers, such as documentation or a test fixture, could never be committed as resolved ("markers remain"). A file now still has markers only when it holds a marker line oxy wrote for its conflicts. A real marker left behind is still caught.

- **A carried switch no longer says carried files were removed (#120).** After a switch that carried the working copy's changes, oxy said new files were "removed from disk" although they were still there. Carried files are now left out of what was removed, and the switch names what it carried.

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.

**Changelog:** a commit that changes code adds a line under `## Unreleased` in CHANGELOG.md (Added, Changed, Fixed or Security, with the issue number); versions change only at release. `scripts/changelog-check.sh [PATH...]` checks it for the paths a commit takes (the working copy's changes without any) and runs in the gate; `NO_CHANGELOG=1` for code changes users won't notice.

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

    }

}

    /// Tag `name`, naming `state`, is withdrawn (spec §10.1): signed by a

    /// key the policy lets create the tag. The name is never used again.

    Untag {

        name: String,

        state: ObjectRef,

        reason: String,

    },

            AttestBody::Untag { .. } => "untag",

            ]),

            AttestBody::Untag {

                name,

                state,

                reason,

            } => Value::map([

                (0, Value::Text(name.clone())),

                (1, Value::Bytes(state.0.to_vec())),

                (2, Value::Text(reason.clone())),

            "untag" => AttestBody::Untag {

                name: text(field(b, 0, "name")?, "name")?.to_owned(),

                state: oref(field(b, 1, "state")?, "state")?,

                reason: text(field(b, 2, "reason")?, "reason")?.to_owned(),

            },

        let u = Attest {

            repo: [1; 16],

            hlc: Hlc::default(),

            body: AttestBody::Untag {

                name: "v1".into(),

                state: ObjectRef([5; 32]),

                reason: "tagged the wrong change".into(),

            },

        };

        assert_eq!(Attest::decode(&u.encode()).unwrap(), u);

        assert_eq!(u.kind(), "untag");

        assert_ne!(u.hash(), t.hash());

//! (or `-binary`), `eol=lf`, `eol=crlf`, `nocompress`, `lockable`, or

//! `merge=union`. A

    /// `merge=union` (oxygen#145): two changes adding lines at the same

    /// place keep both, without asking (`oxy resolve --both`, spec §9.5).

    pub union: bool,

                    ("merge", Some("union")) => a.union = true,

                    ("merge", Some(_)) | ("-merge", None) => a.union = false,

                lockable: false,

                union: false

        let u = Attributes::from_files([(".oxyattributes", &b"CHANGELOG.md merge=union\n"[..])]);

        assert!(u.lookup("CHANGELOG.md").union);

        assert!(u.lookup("docs/CHANGELOG.md").union);

        assert!(!u.lookup("README.md").union);