Levi Neuwirth
b10d5eee88
`run_conditions.index_run_ceiling` offered one value for a raise, and it named a reason: `raised_because_index_sealing_unimplemented`. The emitter never established that reason. It derives the declaration by comparing the configured ceiling with the store default, and a comparison of two numbers cannot know why they differ -- so the bundle asserted a cause on the strength of a subtraction. That was accurate while the unimplemented seal was the only reason to raise the ceiling. Sealing landed, the raise was dropped, and the value became a false explanation waiting for the next run that raises the ceiling for any other purpose -- which the schema would have called valid. `raised_above_store_default` is added and is what the emitter now writes. It states the fact the comparison establishes and stops there. The old spelling is retained and deprecated rather than removed. `schema_version` is `const: 1`, so there is no later version to move archived bundles to, and this repository has never held a bundle to check against; the reference machine may hold ones that declare it. Invalidating evidence already produced is worse than carrying a spelling nothing emits. Deprecated does not mean unchecked, and that was the trap. The `allOf` rule flooring a declared raise at 65 accepts either spelling, so a bundle using the old one is still cross-checked against the recorded ceiling. Had the rule kept keying on the new string alone, the deprecated value would have skipped the cross-check entirely and been valid while recording 64. `both_raised_spellings_are_accepted_and_bound_the_same_way` asserts, for each spelling, that it validates and that it is refused when it records the store default; narrowing the rule to the new value alone fails it. The protocol crate's `submit_path_bundle` keeps the deprecated spelling deliberately, as the standing proof that an archived bundle validates. Recorded as contract review 2026-08-09-B. The scope doc's carry-forward closed on the grounds that the enum was untouched -- true then, superseded now -- so it carries an amendment rather than a rewrite, and its "truthful values today" table now points at the corrections recorded elsewhere in the same document. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JGdH5V43XWnj1PdHqiPktQ |
||
|---|---|---|
| .github/workflows | ||
| bench | ||
| crates | ||
| deploy | ||
| doc | ||
| scripts | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| LICENSE | ||
| README.md | ||
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.mdfor 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 initon 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
fmtandclippyGitHub 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.