Go to file

Levi Neuwirth 93692e2a88 Resolve the target directory instead of assuming it `verify-store-recovery.sh` looked for `store-crash-driver` and `store-bench` under `$repo_root/target/debug`. `CARGO_TARGET_DIR`, a `build.target-dir` in a config.toml, and a shared workspace target all move that, and on a host that sets one the script builds successfully and then exits 70 saying the driver "was not built" - which reads as a compilation failure and is not one. It asks cargo now. The working directory deliberately does not follow. It holds crash roots whose filesystem is part of what the campaign measures, which is why the script already refuses tmpfs; a shared target directory may be on a different one. The distinction is commented so the remaining `$repo_root/target` is not read as a missed substitution. Two scope claims were behind the code and one of them undersold the work. Section 7 said the harness satisfied two of four run conditions. It satisfies three: index sealing earned `index_maintenance = runs_sealed`, derived from the `IndexRun` files read back off the device. `checkpointing` has moved from `unimplemented` to `enabled_not_reached` - the mechanism exists and short runs do not accumulate enough work to trip it - so what remains is a run long enough to take a checkpoint, not a mechanism to build. Section 6.6 item 5 said the emitter wrote a schema-invalid bundle. That closed with `062797d`. The passage is kept rather than deleted because the mechanism is the point: the gate was red for a schema the store satisfied, since three `store-bench` unit tests validate the emitted bundle against the schema rather than against substrings. That is schema conformance living inside the gate, which is what review 2026-07-24-B was after. New carry-forward: `ENGINE_MAX_INDEX_RUNS` outlived its reason. It is 1,000,000 against a store default of 64 and still carries the comment "raised because index-delta sealing is unimplemented", but sealing landed in `fef8520`. Two consequences follow that did not before - the emitted `index_run_ceiling` names a reason that is no longer true, and at that ceiling the fan-out trigger never fires, so `runs_sealed` above is earned by entry pressure alone. It is left as a decision rather than taken: dropping the raise needs the measured run to survive the real ceiling, and renaming the value is an amendment to the lead-owned schema, whose own rule is to request it rather than emit it. Verified on this box at b4e4c7e: `check-phase1.sh` reports GATE_EXIT=0, and `verify-store-recovery.sh --cycles 2` reports matrix=pass, bundle=schema-valid on both paths, acknowledged_loss=0, torn_transactions=0, VERIFY_EXIT=0. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>		2026-08-07 21:35:34 +02:00
.github/workflows	integrate CI and docs	2026-05-01 11:29:18 -04:00
bench	Condition benchmark claims on the run that produced them	2026-07-29 17:38:03 -04:00
crates	Answer reads from a captured root, scoped to one namespace	2026-08-07 21:34:48 +02:00
deploy	levcs 0.1.0 - initial core	2026-05-01 11:14:36 -04:00
doc	Resolve the target directory instead of assuming it	2026-08-07 21:35:34 +02:00
scripts	Resolve the target directory instead of assuming it	2026-08-07 21:35:34 +02:00
.gitignore	levcs 0.1.0 - initial core	2026-05-01 11:14:36 -04:00
Cargo.lock	Implement D0-B storage publication interfaces	2026-07-27 22:31:32 -04:00
Cargo.toml	Implement D0-B storage publication interfaces	2026-07-27 22:31:32 -04:00
LICENSE	integrate CI and docs	2026-05-01 11:29:18 -04:00
README.md	integrate CI and docs	2026-05-01 11:29:18 -04:00

README.md

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

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.

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:

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

Quick start (single user, local only)

# 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:

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:

levcs merge --resolve

Cut a release:

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: build, systemd unit, reverse proxy templates, firewall, and the laptop-side bootstrap.

The compressed version:

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:

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

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:

# 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:

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 — 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 — 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:

Trying it. Run levcs init on a real project, push to a local instance, and report friction.
Workflow design. The next major piece of work is the workflow spec — PR/review surface, issues, CI conventions. Discussion welcome.
Plugin handlers. The wasm plugin protocol exists; concrete handlers (e.g. protobuf, SQL migrations) are needed to validate it.
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 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.

README.md Unescape Escape