Docs: user guide by task (docs/guide.md) and wire protocol for implementers (docs/protocol.md); README links ee06a6c557b7

# Oxygen user guide

This guide is organised by task. It assumes the `oxy` binary is on your

path (`cargo build --release` puts it in `target/release/`). The design

behind every command is in [spec.md](spec.md); this guide only tells you

what to type and what to expect.

Oxygen tracks *changes* rather than snapshots: a change is the set of

edits you made, it commutes with unrelated changes, and conflicts are

recorded in history instead of blocking you. Two ideas recur below:

- A **bookmark** (default `main`) names a *state*: the set of changes it

  contains. A state can have several **heads** when independent changes

  have not been related to each other; that is normal, not a problem.

- The **working copy** is itself a change that Oxygen rewrites every time

  it looks at your files. `oxy commit` turns it into a real change.

Output uses colour and glyphs on a terminal; pipe it, pass `--plain`, or set

`NO_COLOR` for plain ASCII.

## 1. Set yourself up

```

oxy identity create --name "Ada Lovelace" --email [email protected]

oxy config --user core.sign change

```

`identity create` generates a composite Ed25519 + ML-DSA-65 key pair, keeps

the secret in `~/.config/oxy/keys/`, and records you as the default author

in `~/.config/oxy/config.toml`. With `core.sign = change` every commit is

signed; without it, changes are sealed in batches when you push (also

authenticated, just later). Use `--local` to record the identity in one

repository only.

`oxy identity show` prints the key, its expiry, delegates, and whether the

secret is available. `oxy identity export` writes the public identity to a

file to hand to whoever manages a trust policy (section 8).

## 2. Start a repository

```

mkdir project && cd project

oxy init

oxy status

```

`oxy init` creates `.oxy/`. Add `.oxyignore` (gitignore syntax) for files

that should never be tracked; `/target` and `*.tmp` are typical entries.

To take over an existing Git project, see section 12.

## 3. Everyday work

```

oxy status                 # what changed since the last commit

oxy diff                   # the edits, file by file

oxy commit -m "Add retry loop"

oxy log                    # newest first; -n 10, -v for full messages

oxy show 658990aa          # one change by ChangeId prefix, #hash prefix, or @

```

`status` lists each path with a mark: `✚ added`, `✎ modified`, `✖ removed`,

`➜ renamed`, `⚙ mode`. Renames are detected: a removed file and an added

file of the same kind whose contents are at least half alike are recorded

as a move of the same file, so identity survives a rename.

Files containing NUL bytes are stored whole ("opaque"); text files are

stored line by line and merge line by line. `.oxyattributes` overrides the

guess (section 14).

Every change has two names: a **ChangeId** (`658990aa…`) that survives

rewrites, and a content hash (`#7469d16c…`) that changes when the change is

edited. Use whichever you have; prefixes work.

## 4. Fix up history

Oxygen keeps its own record of every operation, so all of these are safe to

try and to undo.

```

oxy describe -m "Better message"        # reword the head the working copy sits on

oxy describe 658990aa -m "..."          # reword any change; dependents are rewritten

oxy amend                               # fold the working copy into the head

oxy amend --into 658990aa               # fold it into an older change

oxy split 658990aa src/parser.rs        # split a head: those paths become a separate first change

oxy abandon 658990aa                    # drop a change; its content stays on disk

oxy undo                                # undo the last operation, whatever it was

oxy op log                              # the operation log

```

Rewriting a change that others depend on rewrites them too, keeping their

ChangeIds. Where a dependent referred to a line that no longer exists, the

reference is re-anchored to the nearest surviving line and `oxy abandon`

prints a note about it.

## 5. Move around

```

oxy checkout                    # the bookmark's heads

oxy checkout 658990aa           # the state of one change and its dependencies

oxy checkout v1.2               # a tag

oxy checkout --discard ...      # throw away uncommitted work first

```

Checking out a single older change gives you the files that change and its

dependencies touch, not a full snapshot from that date: in Oxygen a change

depends only on what it actually builds on.

## 6. Conflicts

A conflict never stops a commit, fetch, or pull. It is recorded in the

state and shown by `oxy status`, which exits with status 2 while any

conflict remains. Conflicted text files are written with markers:

```

<<<<<<< oxy conflict 1 of 2, side 1: change k7m2p9 "Add retry loop"

... lines ...

======= oxy conflict 1 of 2, side 2: change q3x8w1 "Refactor client"

... lines ...

>>>>>>> oxy conflict 1 of 2 end

```

Edit the file to what it should be (keep one side, both, or neither) and

remove the markers. Tree conflicts, such as two files wanting the same

name, appear as `<name>.oxy-conflict-<n>` candidates: keep the one you

want under the right name and delete the rest.

```

oxy resolve      # which conflicts your edits resolve, which still have markers

oxy commit -m "Resolve retry vs refactor"

```

The commit is recorded as a *resolution*, a change that depends on every

side of the conflict; anyone who fetches it gets the conflict resolved.

## 7. Work with others

Run a server (any machine with the repositories under one directory):

```

oxy serve --root /srv/oxy --bind 0.0.0.0:8890 --token SECRET \

          --tls-cert cert.pem --tls-key key.pem

```

Without `--tls-*` the server speaks plain HTTP; keep that on a loopback

address or behind a TLS terminator. `--token` makes pushes require a bearer

token; reads stay open.

On your machine:

```

oxy clone https://host:8890/project

cd project

oxy config remote.origin.token SECRET   # or export OXY_TOKEN

oxy config remote.origin.ca my-ca.pem   # self-signed server: extra roots to trust (or OXY_CA)

oxy push

oxy pull

```

- `oxy fetch` updates `origin/main` without touching your bookmark.

- `oxy pull` fetches, then makes your bookmark the union of both sides.

  There is no merge commit; unrelated changes simply coexist, and a real

  conflict is recorded as in section 6. The working copy follows when it was

  clean.

- `oxy push` sends your changes and moves the remote bookmark. If the remote

  moved since you last fetched, the push is refused: pull and push again.

  `--force` overrides the compare-and-swap.

- `oxy remote add|remove|list` manages remotes; the clone source is `origin`.

A repository can also be cloned from a local path, which is handy for tests

and for a bare "hub" on a shared disk.

## 8. Decide who may publish: the trust policy

Without a policy a repository is *unverified*: everything is accepted and

every remote command says so. A policy names root keys and the keys allowed

to update each bookmark; servers and clients enforce it.

```

oxy policy init                    # your key becomes the only root; push publishes it

oxy policy show

oxy policy grant alice.identity    # alice.identity came from her `oxy identity export`

oxy policy grant ci.identity --pattern 'release/*'

oxy policy revoke 9458b656         # by KeyId prefix

oxy verify                         # signature status of every change in the log

```

Several people can hold root keys:

```

oxy policy root add bob.identity

oxy policy root threshold 2        # future updates need two root signatures

```

Once the threshold is above one, an update you make alone becomes a

*proposal file* (`policy-<serial>.proposal`, or `--out`). Send it to another

root holder, who runs `oxy policy sign policy-7.proposal`; whoever completes

the threshold applies it, and the next push publishes it. Everyone else

picks it up on fetch, verifying each step from the policy they already

trust.

## 9. Keys over time

```

oxy identity rotate                   # fresh key pair; old signatures stay valid

oxy identity renew --expires 365      # same keys, new expiry in days (0 = never)

oxy identity delegate add ci.identity # let another key sign on your behalf

oxy identity delegate remove 3f2a…

oxy identity revoke                   # retire your own key

oxy identity revoke 3f2a… --reason "laptop stolen"   # any key, if you hold a root

```

Rotation, renewal, and delegation all issue a successor identity that names

the previous one. If a policy names your key, it is updated to the successor

in the same step (as a proposal when more root signatures are needed).

Changes signed before the rotation remain authorised; a revoked key

authorises nothing. `oxy verify` shows signatures by revoked keys as valid

but revoked.

## 10. Tags and workspaces

```

oxy tag create v1.2 -m "First release"   # the current heads; or name changes

oxy tag list

oxy workspace add ../project-hotfix      # a second checkout sharing the repository

oxy workspace list

oxy workspace forget ../project-hotfix

```

A tag is an immutable state, signed when you have a key, and travels with

push and fetch. Workspaces have their own working copy and bookmark

(`workspace.bookmark`) but share objects and history.

## 11. Big repositories: partial, sparse, shallow

```

oxy clone URL --max-blob 1M          # files above 1 MiB are fetched on first read

oxy clone URL --sparse src --sparse docs   # materialise only these subtrees

oxy clone URL --depth 50             # only the last 50 levels of history

oxy sparse src docs tests            # change the filter later

oxy deepen 100                       # fetch more history below the boundary

```

Lazy blobs and sparse trees do not affect commits: what you do not have is

left exactly as it was. A shallow clone starts from a *checkpoint* of the

state, so status and commit work at full speed from the first minute.

## 12. Git interoperability

```

oxy git import ../project.git ./project-oxy --branch main   # convert a Git history

oxy git fetch https://github.com/you/project.git            # bring new Git commits in

oxy git push  https://github.com/you/project.git            # publish your changes to Git

oxy git export ../mirror.git                                # a plain Git mirror of the bookmark

```

Import turns each commit into one change (merge commits become

resolutions), keeps authors and hashes as `Git-Author`/`Git-Commit`

trailers, detects renames, and skips submodules. `git fetch`/`git push` keep

a bare mirror under `.oxy/git/`; a push is refused until the remote's tip

has been fetched, so it always fast-forwards. Exported commits carry

`Change-Id` and `Oxy-Hash` trailers.

## 13. Automate: hooks

Executables in `.oxy/hooks/<event>` (never cloned) receive one JSON object

on stdin. `pre-commit`, `pre-push` and other `pre-*` hooks veto by exiting

non-zero, and their stderr becomes the error message. Events:

`pre-commit`, `post-commit`, `pre-push`, `post-fetch`, `post-checkout`, and

`semantic-deps`, which runs at commit when `hooks.semantic-deps = true` and

answers `{"deps": ["<hash>", …]}` to make the change depend on more than it

textually references.

## 14. Per-path attributes, ignores, locks

`.oxyattributes` uses gitattributes syntax:

```

*.png     binary

*.txt     text eol=lf

*.psd     lockable nocompress

```

`binary`/`text` override content sniffing, `eol=lf|crlf` normalises line

endings in the store and on checkout, `nocompress` stores chunks raw, and

`lockable` files are checked out read-only until you take the local lock:

```

oxy lock assets/logo.psd

oxy unlock assets/logo.psd

```

Locks are advisory and local; server-side locks are planned.

## 15. Configuration

Two files, both `key = "value"` lines: `~/.config/oxy/config.toml`

(`oxy config --user KEY VALUE`) and `.oxy/config` (`oxy config KEY VALUE`).

The repository file wins. `OXY_HOME` relocates the user directory.

| Key | Meaning |

|---|---|

| `author.name`, `author.email`, `author.key` | who you are; `key` is set by `identity create` |

| `core.sign` | `change` to sign every commit; otherwise seals at push |

| `core.op-retention` | days for which old operations keep their states alive (90) |

| `core.gc-grace` | days an unreachable object survives (14) |

| `core.checkpoint-interval` | changes between automatic checkpoints (256) |

| `filter.max-blob`, `filter.paths` | lazy blobs and sparse subtrees (section 11) |

| `hooks.semantic-deps` | run the semantic-deps hook at commit |

| `workspace.bookmark` | this workspace's bookmark (`main`) |

| `remote.<name>.url`, `.token`, `.ca` | remotes; token and CA fall back to `OXY_TOKEN` and `OXY_CA` |

## 16. Shell prompt

`oxy prompt` prints `main 658990aa*+2` (bookmark, working copy, `*` dirty,

`!` conflicted, ahead/behind origin) in a few milliseconds and records

nothing. See [prompt.md](prompt.md) for bash, oh-my-bash, zsh, and fish

snippets and the `--format` placeholders.

## 17. Housekeeping

```

oxy gc              # pack loose objects, prune unreachable ones past the grace period

oxy gc --now        # ignore the grace period (only when nothing else is writing)

oxy checkpoint      # serialise the bookmark's state so large histories load instantly

```

Both run automatically: packing when loose objects pile up, checkpoints

every `core.checkpoint-interval` changes.

## 18. If something looks wrong

- **"the remote has change … which you do not; pull first"**: someone

  pushed since your last fetch. `oxy pull`, then push.

- **"policy needs N root signature(s)"** on fetch: the server's policy was

  updated in a way your copy cannot verify. Ask a root holder whether the

  chain of updates was published; a fresh clone trusts the current policy.

- **`oxy status` exits 2**: conflicts remain; see section 6.

- **Many heads on `main`**: independent changes that do not reference one

  another. Nothing to fix; the state is their union.

- **Undo anything**: `oxy undo` reverts the last operation, including

  pulls, checkouts, and rewrites.

# Oxygen wire protocol for implementers

This document describes what a second implementation needs to talk to an

Oxygen server or client: the transport, the message encodings, the order

of requests, and the checks each side performs. It is derived from

[spec.md](spec.md) §5.5, §14, §16 and §17; where the two disagree the

specification wins, and this document says which section to read.

Everything on the wire is deterministic CBOR (§5.1): maps have unsigned

integer keys in increasing order, integers use the shortest form, no

floats, no indefinite lengths, no tags. Objects travel as their canonical

bytes, so the receiver hashes exactly what the sender signed.

## 1. Identifiers and hashing

- **ObjectRef** (32 bytes) = BLAKE3 of `"oxy1 <type> <len>\0" || body`, where

  `<type>` is one of `chunk blob change checkpoint op attest identity policy

  state` and `<len>` is the decimal body length. A ChangeHash is the

  ObjectRef of a change; a KeyId is the ObjectRef of an identity.

- **ChangeId** (16 random bytes) survives rewrites of a change.

- **Repository id** (16 random bytes) is chosen at `init` and returned by

  `capabilities`; a client refuses to push to a repository whose id differs

  from its own.

Object encodings are in spec §5.5 (conventions), §6.1 (change), §11

(checkpoint), §12.1 (op), §14.2 (identity), §14.4 (attestation), §14.5

(policy) and §10.1 (state).

## 2. Transport

The reference server (`oxy serve`) exposes one repository per subdirectory

of its root at `<base>/<repo>/oxy/v1/<endpoint>`:

| Method and path | Body | Response |

|---|---|---|

| `GET  …/capabilities` | — | capabilities |

| `GET  …/refs` | — | refs response |

| `POST …/negotiate` | negotiate request | `{0: [hashes]}` |

| `POST …/fetch` | fetch request | Bundle |

| `POST …/objects` | objects request | Bundle |

| `POST …/checkpoint` | checkpoint request | Bundle |

| `POST …/shallow` | shallow request | `{0: [hashes]}` |

| `POST …/push` | push request | push response |

Rules:

- Request and response bodies are CBOR with `Content-Type:

  application/oxy-cbor`. A body is a single CBOR item (not a sequence).

- Repository names are `[A-Za-z0-9._-]+` and may not start with `.`; anything

  else, and any directory without `.oxy/`, is `404`.

- Reads are unauthenticated. `push` requires `Authorization: Bearer <token>`

  when the server was started with tokens; a missing or wrong token is `401`.

- Errors are plain-text bodies with a 4xx or 5xx status; the client shows the

  text. A push that is *refused* (policy, compare-and-swap) is a `200` with

  `ok = false` in the push response, not an HTTP error.

- TLS is ordinary HTTPS. The reference client trusts the system web roots

  plus an optional PEM file (`remote.<name>.ca` or `OXY_CA`); servers with

  self-signed certificates are expected to hand that file out.

- Pushes to one repository are serialised by the server; reads are not.

The spec (§16) also defines framing for Noise and ZCT transports (`u32

big-endian length || bytes`); the reference implementation speaks HTTP only.

## 3. Messages

Keys are CBOR unsigned integers. `[x]` is an array of x; `bytes(32)` an

ObjectRef; "signed X" is `[X bytes, [Signature]]`.

| Message | Encoding |

|---|---|

| Signature | `{0: key id bytes(32), 1: alg (1 = Ed25519 + ML-DSA-65), 2: Ed25519 bytes(64), 3: ML-DSA-65 bytes(3309)}` |

| Signed attestation | `[attest bytes, [Signature]]` |

| Signed policy | `[policy bytes, [Signature]]` (also the policy proposal file format) |

| Capabilities | `{0: [protocol versions], 1: repo id bytes(16), 2: [feature names]}`; version `1`; features currently `["seal"]` |

| Refs response | `{0: [ref], 1: repo id, 2: signed policy or null, 3: [tag], 4: [signed policy]}` |

| ref | `{0: name, 1: state ref, 2: [heads], 3: signed attestation or null, 4: last serial or null}`; the attestation is present only when it describes the current state; `last serial` is the highest attestation serial ever recorded for the name |

| tag | `{0: name, 1: state ref, 2: [heads], 3: signed attestation or null}` |

| Negotiate request | `{0: [have], 1: [want]}`; response `{0: [hashes]}` in dependency order (no change before its dependencies) |

| Fetch request | `{0: [hashes], 1: max blob size or null}`; response a Bundle whose blobs above the size (and their chunks) are omitted |

| Objects request | `{0: [refs]}`; response a Bundle carrying only objects; a blob is accompanied by its chunks |

| Checkpoint request | `{0: [heads]}`; response a Bundle of objects: the checkpoint of exactly those heads, its payload blob, and the blob's chunks; the server computes one when it has none for those heads |

| Shallow request | `{0: [heads], 1: depth}`; response `{0: [hashes]}`: the changes within `depth` dependency steps of the heads, dependencies first |

| Bundle | `{0: [[change bytes, [Signature]]], 1: [signed attestation], 2: [[type name, object bytes]], 3: [signed policy]}` |

| Push request | `{0: Bundle, 1: [update], 2: signed policy or null, 3: [tag]}` |

| update | `{0: name, 1: old state ref, 2: new state ref, 3: force (bool), 4: signed attestation or null}` |

| Push response | `{0: [{0: name, 1: ok (bool), 2: reason (text)}]}`; a result named `policy` reports the policy update, `tags/<name>` each tag |

Bundle details:

- Changes are in dependency order, each with its individual signatures

  (possibly none).

- Key 1 carries seals (`kind = seal`) covering the changes.

- Key 2 objects are only `chunk`, `blob`, `identity`, `state`, `checkpoint`;

  a receiver rejects any other type.

- Key 3 (optional) carries the policies between the receiver's serial and

  the one in the push request, ascending, so the receiver can verify each

  step (§14.5). The refs response carries the same history in its key 4.

Sizes: a seal lists at most 4096 hashes, sorted and unique. Chunks are

32–256 KiB (FastCDC, average 64 KiB, gear table from the BLAKE3 XOF of

`"oxy1 fastcdc gear"`, spec §13.2); a receiver re-hashes every object.

## 4. Sequences

### 4.1 Clone or fetch

1. `capabilities`: check protocol version 1 and record the repository id.

2. `refs`: for each wanted bookmark note `state`, `heads`, `attestation`;

   take the policy and history.

3. Policy (spec §14.5): with no local policy, accept the remote's if it is

   for this repository and carries a valid signature by one of its own roots

   (trust on first use). With a local policy, refuse a lower serial or a

   different policy at the same serial; otherwise verify each policy in the

   chain against the one before it (signatures by the previous roots meeting

   the previous threshold, serial strictly increasing) and adopt them in

   order. Record the highest serial this remote has ever presented and

   refuse a remote that later presents none or a lower one.

4. `negotiate` with `have` = local heads of every bookmark, `want` = the

   remote heads. The response lists the missing changes.

5. `fetch` those hashes (with `max blob size` for a partial clone). Store

   objects, changes and seals; verify every change's signatures and seals;

   under a policy, authenticate each new change (§14.4: signer is the author

   or a delegate of the author) and check it is authorised for the bookmark

   by the first matching rule (a rule key covers its rotation predecessors,

   and a delegate's signature counts for the author).

6. Verify the bookmark's attestation (`kind = ref`: repo id, name, old

   state, new state, serial) against the policy and against the serial you

   last recorded for that reference (rollback protection), then update

   `remotes/<name>/<bookmark>`.

7. Tags: adopt those not yet held, checking their attestations the same way.

A shallow clone replaces steps 4–5 by `shallow` (the hashes within the

depth) plus `checkpoint` for the heads, and fetches only the listed changes;

their missing dependencies form the boundary. Lazy blobs are fetched later

with `objects`.

### 4.2 Push

1. `capabilities` and `refs` as above; refuse if the remote's policy is

   newer than yours (fetch first).

2. Compute the changes the remote lacks (`negotiate` with the roles

   reversed, or locally from the remote heads), bundle them in dependency

   order with their signatures, seal your unsigned changes with one `seal`

   attestation, and attach identities, blobs, chunks and the new state

   object.

3. Attest the reference: `kind = ref` with `serial` = the remote's `last

   serial + 1`, signed by your key.

4. Send `push` with `old state` = the state the remote reported (empty

   state ref when the bookmark is new), the new state, and your policy with

   its intermediate history when the remote's serial is behind.

### 4.3 What a server checks on push

In this order, spec §16.4: adopt the policy chain if present (each step

verified against the previous policy); import the bundle, verifying every

object's hash and, under a policy, every change's authentication and

authorisation; verify the reference attestation (signer authorised for the

name, serial above the last recorded); check `old state` equals the current

state (compare-and-swap; `force` skips this check only); check the rule's

`allow_conflicts` and `require` (signed, sealed, any); check every

dependency of every change is present; then update the references

atomically and record the attestation. Any failure rejects the whole push

with `ok = false` and a reason.

## 5. Minimal implementations

A **read-only client** needs: CBOR decode, BLAKE3, the change and state

decoders, `capabilities`/`refs`/`negotiate`/`fetch`, and the ability to

materialise a state (spec §7–§9). Signature verification (Ed25519 and

ML-DSA-65) is required to honour a policy; without it, treat every

repository as unverified and say so.

A **server** needs the above plus storage, the push checks of §4.3, per-

repository write serialisation, and the policy chain (`refs` key 4, bundle

key 3). It never needs a private key of its own: servers store and forward

signatures, they do not make them.

Test material: the encoders and decoders in `crates/oxy-core/src/protocol.rs`

(`wire` module) and the round-trip and corruption tests beside them; the

signature vectors in `crates/oxy-core/src/identity.rs`; and the chunking

bounds test in `crates/oxy-core/src/chunk.rs`.

Oxygen (`oxy`) is a distributed, commutative version control system written in Rust for large repositories. See [docs/spec.md](docs/spec.md) for the specification, [docs/guide.md](docs/guide.md) for a user guide by task, and [docs/protocol.md](docs/protocol.md) if you are implementing a client or server.

| `docs/guide.md` | User guide, organised by task |

| `docs/protocol.md` | Wire protocol for other implementers |

| `docs/prompt.md` | Shell prompt integration |

- [x] Documentation: `docs/guide.md` (user guide by task) and `docs/protocol.md` (for other implementers, derived from spec §16 and the wire encodings). (Done; every command and flag in the guide was checked against `--help`.)

- 2026-09-27 09:35 iteration 17: user guide and protocol document. 112 tests.