# LeVCS

A distributed version control system with first-class federation, signed
authority chains, and a cascading merge engine. Content-addressed by
BLAKE3, signed with Ed25519, and built to fix what git can't.

> **Status: v0.1.0 — protocol substrate complete, workflow surface deferred.**
> The object model, federation API, merge cascade, and instance server
> all work end-to-end. There is no PR review surface, issue tracker, or
> web UI yet — those are the next layer up. See
> [`doc/technical-report.md`](doc/technical-report.md) for a full
> framing of where this project is and why.

---

## What's different from git

- **Identity is in the protocol.** A repo's membership is a versioned,
  signed authority object with explicit roles
  (Reader/Contributor/Maintainer/Owner). Force-push enforcement and
  push authorization are protocol-level, not server policy.
- **Federation is first-class.** Every repo has a global `repo_id`
  (BLAKE3 of its genesis authority); instances mirror each other in
  three storage modes (full / release-only / metadata-only).
- **Merge is a cascade**, not a line-level diff. Per-file dispatch to
  a handler ranked by aggressiveness: textual fallback, format-aware
  (JSON / YAML / TOML / XML / Markdown / prose), tree-sitter for
  source code (Rust, Python, JS/TS, Go, C/C++, Java, Ruby, Bash), and
  wasm-sandboxed plugins for the long tail.
- **BLAKE3, not SHA-1.** Tree-hashed, ~5 GiB/s on a laptop, 32-byte
  IDs everywhere.
- **Releases are signed objects**, not mutable name pointers.

For a deeper comparison and context, see the
[technical report](doc/technical-report.md).

---

## Building

LeVCS is a Rust workspace. You'll need a recent stable toolchain
(workspace MSRV is 1.75) and a C compiler for the tree-sitter grammars.

```sh
cargo build --release
```

Two binaries land in `target/release/`:

- `levcs` — the user-facing CLI.
- `levcs-instance` — the federation HTTP server.

Install them somewhere on `PATH`:

```sh
sudo install -m 0755 \
    target/release/levcs target/release/levcs-instance \
    /usr/local/bin/
```

---

## Quick start (single user, local only)

```sh
# Generate an identity key (stored in $XDG_CONFIG_HOME/levcs/keys.toml).
levcs key generate --label me

# Create a repository wherever you have files to track.
mkdir /tmp/demo && cd /tmp/demo
echo "hello" > a.txt

levcs init --key me
levcs track --all
levcs commit -m "first commit"
levcs log
```

That's a fully working LeVCS repo. Branch and merge:

```sh
levcs branch feature/x
echo "more" >> a.txt
levcs commit -m "wip"
levcs branch main
levcs merge feature/x
```

If a merge produces conflicts, drop into the resolution TUI:

```sh
levcs merge --resolve
```

Cut a release:

```sh
levcs release v0.1.0 --notes "first release"
```

---

## Hosting an instance

To dogfood the federation surface, run `levcs-instance` on a VPS behind
nginx or Caddy. The full walkthrough is in
[`deploy/README.md`](deploy/README.md): build, systemd unit, reverse
proxy templates, firewall, and the laptop-side bootstrap.

The compressed version:

```sh
sudo cp deploy/levcs-instance.service /etc/systemd/system/
sudo cp deploy/instance.toml.example /etc/levcs/instance.toml
sudo $EDITOR /etc/levcs/instance.toml
sudo systemctl enable --now levcs-instance
# ... then drop deploy/Caddyfile.example into /etc/caddy/Caddyfile
```

From your laptop, point the local repo at the instance and push:

```sh
levcs instance --set https://levcs.example.com/levcs/v1
levcs push refs/branches/main
```

The first push to a fresh instance auto-inits the repo with your
genesis authority. Subsequent pushes are role-checked against the
authority chain.

---

## Repository layout

```
crates/
  levcs-core/        Object model (Blob/Tree/Commit/Release/Authority),
                     hash, store, refs, repository abstractions.
  levcs-identity/    Authority objects, Ed25519 keys, signing/verify.
  levcs-merge/       Cascade engine, format and tree-sitter handlers,
                     plugin runtime, merge records.
  levcs-protocol/    Pack codec, wire types, request signing, P2P.
  levcs-client/      Thin HTTP client over the federation API.
  levcs-instance/    Axum HTTP server (the federation peer).
  levcs-cli/         The `levcs` user-facing CLI.
  levcs-tui/         Conflict-resolution terminal UI.

deploy/              Production deployment artifacts (systemd, Caddy, nginx).
scripts/             Reproducible benchmark and ops scripts.
doc/                 Technical report and architecture docs.
.github/workflows/   CI configuration.
```

---

## Testing

```sh
cargo test --workspace
```

Runs the full suite — unit tests, integration tests, federation
end-to-end tests including the three-instance "dogfood" scenario, the
merge conformance corpus, and property-based fuzz tests. ~194 tests at
v0.1.0; full run is well under a minute on a modern laptop.

Useful subsets:

```sh
# A single crate's tests
cargo test -p levcs-merge

# A specific integration test
cargo test -p levcs-instance --test dogfood

# Property tests only
cargo test -p levcs-merge --test proptest_textual
```

---

## Benchmarks

Microbenchmarks live in each crate's `benches/` directory and use
`criterion`. A reproducible runner with metadata capture and optional
flamegraph generation is at `scripts/bench.sh`:

```sh
scripts/bench.sh --quick               # smoke test (~ a minute total)
scripts/bench.sh                       # full criterion run (~ a few minutes)
scripts/bench.sh --flamegraph          # generate per-bench SVG flamegraphs
scripts/bench.sh --bench pack_codec    # one bench only
```

Output goes to `bench-results/<host>-<UTC-timestamp>/` with a parsed
`summary.txt`, criterion's HTML reports, and a `metadata.txt` capturing
rustc version, kernel, CPU, and git rev for run-to-run comparison.

Headline numbers on a Ryzen 7 laptop:

- **Pack decode** at 10 × 1 MiB entries: ~2.3 ms (4.3 GiB/s).
- **Blob serialize + BLAKE3** at 1 MiB: ~190 µs (5.1 GiB/s).
- **Textual three-way merge** of a 100 KiB document: ~4.6 ms.

Pack encoding is the throughput floor at ~380 MiB/s — bottlenecked by
zstd level 3 on incompressible data.

---

## Documentation

- **[`doc/technical-report.md`](doc/technical-report.md)** — Distribution
  document. What LeVCS is, how to use it, and how it differs from /
  improves upon git. Targets technical evaluators and the workflow-spec
  reader.
- **[`deploy/README.md`](deploy/README.md)** — Comprehensive VPS
  deployment walkthrough.
- **`spec/`** — The protocol specification and trust-root revision.
  Currently kept private; ask the maintainer for a copy.

---

## Contributing

This is a young project. The most useful contributions right now are:

1. **Trying it.** Run `levcs init` on a real project, push to a local
   instance, and report friction.
2. **Workflow design.** The next major piece of work is the workflow
   spec — PR/review surface, issues, CI conventions. Discussion welcome.
3. **Plugin handlers.** The wasm plugin protocol exists; concrete
   handlers (e.g. protobuf, SQL migrations) are needed to validate it.
4. **Tightening CI.** The `fmt` and `clippy` GitHub jobs are
   informational; flipping them to gating would close a small but real
   quality gap.

Please open an issue or reach out before starting non-trivial work so
we can coordinate.

---

## License

Released under the Apache License 2.0 — see [`LICENSE`](LICENSE) for the
full text.

---

## Citation

If LeVCS supports academic work, please cite the v0.1.0 release. A
formal citation entry will land with the workflow spec; in the meantime
a repository-URL reference is fine.