wvc 0.1.0__tar.gz

wvc-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+# Weights and run artifacts stay out of Git.
+*.safetensors
+# The tiny spec test vectors are tracked.
+!spec/vectors/**/*.safetensors
+*.gguf
+*.npz
+models/
+runs/
+.coverage
+htmlcov/
+# E003 end-to-end repository and checkouts hold weights.
+experiments/E003/repo/
+experiments/E003/checkout-*/
+# A wvc repository created inside this source tree holds weight payloads.
+.wvc/
+# E004 holds a training run, generations, and a wvc repository with weights.
+experiments/E004/repo/
+experiments/E004/raw/
+experiments/E004/checkpoints/
+experiments/E004/merged/
+experiments/E004/work/
+
+# macOS
+.DS_Store
+# E005 repository and checkouts hold weights.
+experiments/E005/repo/
+experiments/E005/checkout-*/
+.hypothesis/
+CLAUDE.local.md

wvc-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+User-visible changes, newest first. Releases are git tags `vX.Y.Z`: CI publishes a tag to PyPI after the checks pass, and a tag must name a section here.
+
+## 0.1.0
+- Hardened against hostile input before this first release, following two rounds of code and security review: a checkpoint, store, or remote controlled by someone else can make wvc refuse, never write outside the directory you named, run code, or report bytes as verified that are not. What it refuses, and why: tensor records above `max_tensor_bytes` (16 GiB by default, 1 TiB at most) and frames that do not match their record, so a kilobyte store cannot claim gigabytes; shapes over 64 dimensions and headers with more brackets than tensors could need; non-regular input files and symbolic links out of a checkpoint; remote files larger than their records imply; a stored object that does not decode back to its tensor id; `--force` replacing a file no earlier checkout wrote unless named with `--overwrite`; and values longer than 40 characters in any message. Checkouts check free disk space first and move existing files aside so a failed rename restores them; every wvc error exits 2, a bug propagates as a traceback, and `WVC_DEBUG=1` re-raises. The documented limits are in `SECURITY.md`.
+- First release: `hash`, `diff`, and `verify` on local and Hub checkpoints; repositories with `init`, `commit`, `log`, `show`, `checkout`, and `fsck`; `bisect`; `merge-adapter`; `card`; `remote`, `push`, `pull`, and `clone`; spec v0 with conformance vectors under `spec/vectors/v0`.
+- `wvc --version` prints the version.
+- A `v*` tag on a `main` commit publishes the sdist and wheel to PyPI through trusted publishing (`.github/workflows/release.yml`), after the tag is checked against the project version and this changelog, the checks pass on Ubuntu, and the sdist is checked to hold only the package, tests, conformance vectors, and top-level documents.
+- `wvc diff --rank` estimates the rank of touched blocks up to 2^26 elements, so a 9B-class projection matrix gets a rank without `--rank-cap`. The block is decoded to float64 and copied twice, so a block at the cap peaks near 1.1 GiB of memory and can take about 20 s.
+- `wvc hash`, `wvc diff`, and `wvc verify` accept a Hub repository as `hf:OWNER/NAME[@REVISION]` (install the `hf` extra); a diff of two Hub repositories fetches only the shards whose Hub hashes differ and reports the rest unchanged from their headers.
+- `wvc hash --format gguf-hash` prints llama.cpp gguf-hash manifest lines for a safetensors checkpoint.

wvc-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to wvc
+
+wvc has one maintainer. Bug reports, use cases, reviews, and small focused pull requests are welcome. Open an issue before starting anything large.
+
+## Scope and non-goals
+- In scope (v0): `hash`, `diff`, `verify`, and a local object store with `init`, `commit`, `log`, `show`, and `checkout`; remotes as plain directories first, then the Hugging Face Hub and OCI registries. The formats are specified in [docs/spec-v0.md](docs/spec-v0.md).
+- Non-goals: hosting, git filters, a UI, lossy-only storage (a checkout must reproduce bytes exactly), and runtime dependencies beyond numpy and zstandard (no PyTorch).
+- Scope, identity, and licence are maintainer decisions; the chosen formats are in [docs/spec-v0.md](docs/spec-v0.md), and the reasoning behind each one is kept in the maintainer's research notes outside this repository. Work outside them needs an issue and a recorded decision first.
+
+## Running the checks
+CI runs these commands on Ubuntu, macOS, and Windows with Python 3.11 and 3.13.
+
+```bash
+uv sync
+uv run ruff check .
+uv run ruff format --check .
+uvx ty@0.0.95 check src
+uv run pytest -p randomly --cov=wvc --cov-report=term-missing --cov-fail-under=95
+```
+
+- The test run is in random order (pytest-randomly prints its seed in the header; `--randomly-seed=N` repeats an order), treats every warning as an error (`filterwarnings = ["error"]` in `pyproject.toml`), and fails below 95% line coverage. If a third-party warning appears on one platform, ignore that one message in `filterwarnings` rather than dropping the setting.
+- `tests/test_header_fuzz.py` fuzzes both safetensors header parsers with Hypothesis (200 examples per property, a few seconds in all).
+- On Ubuntu only, CI also runs `uvx codespell .` with the skip list in `[tool.codespell]` in `pyproject.toml`; words that are correct here go in its `ignore-words-list`.
+- A `package` job runs `uv build`, `uvx twine check dist/*`, and `validate-pyproject`, and fails if the sdist holds anything beyond the package, its tests, the conformance vectors, and the top-level documents.
+- An `audit` job runs `pip-audit` on the locked dependencies (`uv export` then `uvx pip-audit -r requirements.txt --disable-pip --no-deps`) on every push and every Monday at 06:00 UTC; it does not block the test matrix.
+- CI installs with `uv sync --locked`, so commit `uv.lock` together with any dependency change. CI pins the `ty` version it runs; bump the pin in `.github/workflows/ci.yml` deliberately.
+- Tests use small synthetic safetensors fixtures and must not download weights or need the network.
+- Never commit weights or run artifacts (`*.safetensors`, `*.gguf`, `*.npz`, `models/`, `runs/`).
+
+## Experiments and receipts
+- Every experiment gets an ID (E001, E002, ...) and a receipt under [experiments/](experiments/): commands, input revisions and hashes, tool versions, the code revision, and outputs.
+- Numbers are never restated in prose (README, docs, issues, pull requests) without a link to the receipt they come from. Receipts outrank summaries.
+- Negative and failed results get receipts too.
+
+## Commit messages
+- Use `type: description`, where type is one of `feat`, `fix`, `docs`, `test`, `chore`, `refactor`, `perf`, or `ci`; for example `docs: record the code revision for E001`.
+- No attribution trailers (no `Co-Authored-By:` or "Generated with" lines).
+
+## Code style
+- numpy and zstandard are the only runtime dependencies.
+- Keep functions small and single-purpose.
+- Validate explicitly at boundaries (file headers, manifests, CLI arguments) and raise clear errors.
+- No `no `print` outside the CLI modules (`cli*.py`)
+- Line length is 100; ruff enforces formatting and the lint rules in `pyproject.toml`.
+
+## Licence
+wvc is licensed under the [Apache License 2.0](LICENSE). Contributions are accepted under the same licence.

wvc-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

wvc-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.5
+Name: wvc
+Version: 0.1.0
+Summary: Version control primitives for model weights: tensor-level hashing and diffs of safetensors checkpoints, without PyTorch.
+Project-URL: Homepage, https://github.com/evnsnclr/wvc
+Project-URL: Repository, https://github.com/evnsnclr/wvc
+Project-URL: Issues, https://github.com/evnsnclr/wvc/issues
+Project-URL: Changelog, https://github.com/evnsnclr/wvc/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/evnsnclr/wvc/blob/main/SECURITY.md
+Author: Evan Smith
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: checkpoints,model weights,provenance,safetensors,version control
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: zstandard>=0.22
+Provides-Extra: hf
+Requires-Dist: huggingface-hub>=1; extra == 'hf'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/hero.svg" width="100%" alt="wvc: version control for open model weights. Animation of a real diff: two Qwen3.5-9B checkpoints on the Hugging Face Hub are compared shard by shard. Three of the four shards have the same SHA-256 on both sides and are skipped, the fourth is fetched, and one of its 53 tensors, layer 17's mlp.down_proj.weight, lights up as changed, with rank 1.">
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#what-it-found">What it found</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#commands">Commands</a> ·
+  <a href="#status">Status</a> ·
+  <a href="docs/spec-v0.md">Spec</a> ·
+  <a href="experiments/">Receipts</a>
+</p>
+
+<p align="center">
+  <img alt="Release: none yet" src="https://img.shields.io/badge/release-none%20yet-8b949e">
+  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-3776ab">
+  <a href="LICENSE"><img alt="Licence: Apache-2.0" src="https://img.shields.io/badge/licence-Apache--2.0-2ea44f"></a>
+  <a href="https://github.com/evnsnclr/wvc/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/evnsnclr/wvc/actions/workflows/ci.yml/badge.svg"></a>
+</p>
+
+**wvc is an experimental tool that treats a model checkpoint as a set of tensors, not one opaque file.** It gives every tensor an id (the SHA-256 of its bytes), shows exactly which tensors two checkpoints disagree on and how (elements, rows, columns, rank), and stores a new revision as deltas against its parent that check out byte for byte. It reads safetensors with numpy alone, needs no PyTorch or GPU, and can diff two Hugging Face Hub repositories while downloading only the shards that differ.
+
+Open-weight models change through fine-tunes, merges, adapters, abliteration, and, [since November 2026](https://rikiyat.github.io/blog/weight-space-programming/), direct edits written by LLM agents. The Hub records each change as new files and a model card that names a parent with [one of four words](https://huggingface.co/docs/hub/model-cards). A card that says `finetune` doesn't say which weights moved, and safety, interpretability, and supply-chain work all need to know.
+
+<p align="center">
+  <img src="docs/assets/demo.svg" width="100%" alt="A terminal runs wvc diff --rank hf:Qwen/Qwen3.5-9B hf:bowmanslayer/Qwen3.5-9B-Evil-BF16. Output: 4 shards per side, 3 byte-identical on the Hub and skipped, 1 fetched from each side; 775 tensors, 1 changed; 46,281,237 of 9,653,104,368 elements changed (0.4794%); the changed tensor is model.language_model.layers.17.mlp.down_proj.weight, BF16 [4096,12288], every row and column touched, rank 1, top-1 energy 0.9997.">
+</p>
+<p align="center"><sub>The command and output of a real run, repeated on 2026-11-03 with output byte-identical to its <a href="experiments/README.md">receipt</a>. The animation compresses time: from the Hugging Face cache the run takes 15 to 40 s on an M4 Max; the first run also downloads the two shards that differ (10.67 GB).</sub></p>
+
+## What it found
+
+Two public weight changes and what `wvc diff` reports for them. The figure is drawn from the bytes of both checkpoints by [`make_deltas.py`](docs/assets/make_deltas.py), which first checks every count against the receipts.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/deltas-dark.png">
+  <img src="docs/assets/deltas-light.png" width="100%" alt="Heat maps of |edited − base| for every changed tensor. Left: two 1024 × 3584 down-projection matrices of Qwen3.5-0.8B, in which only 64 thin columns changed. Right: one 4096 × 12288 down-projection matrix of Qwen3.5-9B, changed almost everywhere in a striped, rank-1 pattern.">
+</picture>
+
+| | An edit written by an LLM agent | An upload that names no tensor |
+|---|---|---|
+| **Pair** | `Qwen/Qwen3.5-0.8B` → `RikiyaT/Qwen3.5-0.8B-weight-space-programming` | `Qwen/Qwen3.5-9B` → `bowmanslayer/Qwen3.5-9B-Evil-BF16` |
+| **The card says** | the two edited tensors and their hashes ([Weight-Space Programming](https://rikiyat.github.io/blog/weight-space-programming/)) | `finetune`, with no method and no tensor named |
+| **wvc finds** | 2 of 488 tensors: 64 of 3,584 columns of `mlp.down_proj` in layers 15 and 19, rank 1 each | 1 of 775 tensors: layer 17's `mlp.down_proj`, 92% of its weights, rank 1 (top-1 energy 0.9997) |
+| **Check** | changed counts and hashes equal the authors' own manifest | none beyond the bytes: no method was published |
+| **Read** | one 1.7 GB file per side; the diff took 9.8 s on an M4 Max | 1 of 4 shards per side: 10.67 of the pair's 38.61 GB |
+
+A diff shows where a model changed and how, not what the change does.
+
+## Quick start
+
+wvc is not on PyPI yet. Install it from a clone with [uv](https://docs.astral.sh/uv/) (Python 3.11 or newer):
+
+```bash
+git clone https://github.com/evnsnclr/wvc && cd wvc
+uv sync --extra hf   # the hf extra reads Hub repositories; plain `uv sync` is enough for local files
+```
+
+Diff the two sub-kilobyte checkpoints that ship with the [spec's conformance vectors](spec/vectors/v0/README.md); nothing is downloaded:
+
+```bash
+uv run wvc diff --rank spec/vectors/v0/a.safetensors spec/vectors/v0/b.safetensors
+```
+
+```text
+tensors: 4 (1 changed, 1 unchanged, 1 added, 1 removed, 0 reshaped)
+elements changed: 4 of 32 (12.5000%)
+
+status   tensor  dtype     shape    changed  rows  cols  max|d|  |d|/|a|  rank  top1
+removed  h       F16       [2,2,2]  -        -     -     -       -        -     -
+changed  w       F32       [4,6]    4/24     4     1     1       0.418    1     1.0000
+added    x       None->I8  [3]      -        -     -     -       -        -     -
+```
+
+Then a real pair from the Hub (the first run downloads 1.7 GB per side into the Hugging Face cache):
+
+```bash
+uv run wvc diff --rank hf:Qwen/Qwen3.5-0.8B hf:RikiyaT/Qwen3.5-0.8B-weight-space-programming
+```
+
+Keep revisions in a repository and get the exact files back:
+
+```bash
+export WVC_AUTHOR="Your Name"   # commits never record an author silently
+uv run wvc init demo
+uv run wvc commit spec/vectors/v0/a.safetensors -m "base" --op pretrain-checkpoint --repo demo
+uv run wvc commit spec/vectors/v0/b.safetensors -m "add 1.0 to column 2 of w" --op direct-edit --repo demo
+uv run wvc log --repo demo
+uv run wvc checkout HEAD --out restored --repo demo
+```
+
+<details>
+<summary>What that prints</summary>
+
+Commit ids include the time and the author, so yours will differ.
+
+```text
+initialised an empty wvc repository in /path/to/wvc/demo/.wvc
+commit b44ff44ddbce97c02cad0786047c939e1d54f70c25ca5d0320d5dd16d5cc0956 (main, no parent)
+tensors: 3 (0 reused by hash, 3 stored full, 0 stored as delta)
+payload bytes written: 448 in 0.01 s
+commit 8461fce5701f28ae37aafd431ec8d2cdfa372be949f78105139078f715f68216 (main, parent b44ff44ddbce)
+tensors: 3 (1 reused by hash, 1 stored full, 1 stored as delta: 1 delta-xor-planes)
+payload bytes written: 364 in 0.01 s
+8461fce5701f  2026-11-03T17:43:19Z  direct-edit          3 tensors  add 1.0 to column 2 of w
+b44ff44ddbce  2026-11-03T17:43:19Z  pretrain-checkpoint  3 tensors  base
+checked out 8461fce5701f into restored: 1 file, 355 bytes in 0.00 s
+b.safetensors  355 bytes  sha256 ok
+manifest root 226839773eb209266cbb929481b4e106d483eec17361879692c0bd87789b15cc verified against the files
+```
+
+</details>
+
+`diff` exits 1 when the checkpoints differ, like `diff(1)`; `verify` exits 0 only when every tensor and the root match; every wvc error exits 2. Add `--json` for a machine-readable record.
+
+## How it works
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/how-dark.svg">
+  <img src="docs/assets/how-light.svg" width="100%" alt="Three panels with real values from the receipts. wvc hash: each tensor's bytes get a SHA-256, and the sorted manifest lines get a root. wvc diff: of four layer-15 tensors only mlp.down_proj has a different id, so only it is decoded: 65,260 weights in 64 of 3,584 columns, rank 1. wvc commit and checkout: the edited revision reuses 486 tensors by id and stores 2 deltas of 513 KB; checkout writes a file whose SHA-256 equals the Hub's.">
+</picture>
+
+1. **Identity.** A tensor's id is the SHA-256 of its stored bytes; a manifest lists every tensor's name, dtype, shape, and id, and its root is a SHA-256 over those lines. Sharding, header order, and file names don't change the root ([spec §1](docs/spec-v0.md#1-tensor-identity-and-manifests-implemented)).
+2. **Diff.** Tensors with equal ids are never decoded. The rest are decoded exactly (BF16, FP16, FP8, and the rest; a dtype that can't be decoded gets a byte-level count) and compared element by element: changed count, rows and columns touched, largest change, relative norm, and an SVD rank estimate. Across two Hub repositories, a shard whose name, size, and SHA-256 agree is skipped; its tensors are reported from its header, read by range request ([spec §5.5](docs/spec-v0.md#55-hub-checkpoints-implemented-2026-11-03)).
+3. **Store.** `commit` keeps each tensor once by id and stores a changed tensor as an XOR-plane or sparse delta against its parent when that is smaller. It also records every file's header bytes and the non-tensor files a loader needs (config, tokenizer, chat template), so `checkout` rebuilds the original files and checks each one's SHA-256 before it appears ([spec §3](docs/spec-v0.md#3-repository-objects-and-deltas-implemented-2026-11-02)).
+
+## Storage
+
+Bytes needed to store a revision given its parent, as a share of its raw tensor bytes (smaller is better), on four public pairs:
+
+| Revision pair | Compress each tensor (zstd) | Byte-chunk dedup, best case | wvc delta |
+|---|---|---|---|
+| Qwen3.5-0.8B → weight-space edit (sparse rank-1 edit, 1.75 GB) | 78.2% | 0.66% | 0.030% |
+| Qwen2.5-0.5B + rank-8 merge (synthetic adapter merge, 988 MB) | 77.8% | 3.51% | 1.67% |
+| pythia-160m, step 142k → 143k (consecutive pretraining checkpoints, 649 MB) | 58.0% | 58.0% | 33.6% |
+| Qwen2.5-0.5B → Instruct (dense post-training fine-tune, 988 MB) | 77.9% | 77.9% | 56.3% |
+
+Byte-level chunk dedup, fixed or content-defined, found nothing beyond whole-tensor identity on any of four public revision pairs: a fine-tune rewrites bytes in place, and a 64 KiB chunk can't see one changed element. Numeric deltas can. On the sparse edit a delta needs 22× fewer bytes than tensor dedup alone (0.53 MB against 11.5 MB), on the synthetic rank-8 merge 2.1× fewer, and on dense updates it saves a modest 21% to 27% beyond byte-grouped compression. In a wvc repository the LLM-written edit costs 513 KB on top of a 1.245 GB base, and both revisions check out hash-identical to the Hub's files.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `wvc hash CKPT` | Print a manifest: every tensor's SHA-256 and a root. `--format gguf-hash` prints llama.cpp's `gguf-hash` lines instead. |
+| `wvc diff A B` | Compare two checkpoints tensor by tensor. `--rank` estimates the rank of each change, `--all` lists unchanged tensors too. |
+| `wvc verify CKPT MANIFEST` | Check a checkpoint against a manifest saved from `wvc hash`. |
+| `wvc init`, `commit`, `log`, `show`, `checkout` | A local repository: tensors stored once by id, changes as deltas, files rebuilt byte for byte. |
+| `wvc fsck` | Re-verify every payload, object, manifest, commit, and ref in a repository. |
+| `wvc bisect GOOD BAD --test CMD` | Find the first commit where a behavioural test fails (`--sweep` tests every commit instead). |
+| `wvc merge-adapter BASE ADAPTER` | Merge a PEFT LoRA adapter deterministically and store its targets as low-rank deltas. |
+| `wvc remote`, `push`, `pull`, `clone` | Move commits between repositories: plain directories, or Hub repositories with the `hf` extra. |
+| `wvc card REF` | Print model-card metadata that carries the manifest root. |
+
+`CKPT` is a `.safetensors` file or a directory of shards; `hash`, `diff`, and `verify` also take a Hub repository as `hf:OWNER/NAME[@REVISION]`. Without `--repo`, repository commands use the nearest `.wvc/` above the current directory.
+
+## Status
+
+- **Run on real models:** `hash`, `diff`, and `verify`, on local files and on the Hub; `commit`, `checkout`, and `fsck`, with byte-identical files and a checkout that loads in transformers with identical logits; `bisect` on a real fine-tuning run, where the behaviour had no single onset and bisect said so. Each run has a [receipt](experiments/README.md).
+- **Unit-tested, not yet run on real models:** `merge-adapter`, remotes (directory and Hub), `card`.
+- **Not built:** reading GGUF (wvc only writes `gguf-hash` lines), signing and attestation, garbage collection, a release.
+- **Not planned:** hosting, a UI, git filters, lossy storage, PyTorch at runtime.
+
+CI runs the tests, ruff, and a type check on Ubuntu, macOS, and Windows with Python 3.11 and 3.13, with warnings as errors, a coverage floor, a dependency audit, and header-parser fuzzing. Every measurement so far comes from one machine (an Apple M4 Max), safetensors files, and the model families named in the receipts. [SECURITY.md](SECURITY.md) describes how wvc handles untrusted input and lists its known limits.
+
+## Receipts
+
+Each experiment has a record under [experiments/](experiments/README.md): the question, predictions written before the run, exact commands, input revisions and hashes, tool versions, raw outputs, and which predictions failed. Every number in this README comes from one of them; the index lists each run, including the negative result.
+
+## Contributing
+
+wvc has one maintainer, and the most useful contributions right now are real checkpoint pairs that break it, use cases, and reviews. Read [CONTRIBUTING.md](CONTRIBUTING.md) first. Security reports go through GitHub's private vulnerability reporting; see [SECURITY.md](SECURITY.md).
+
+The figures here are drawn from the receipts by [`docs/assets/make_figures.py`](docs/assets/make_figures.py) and, from the weights themselves, by [`docs/assets/make_deltas.py`](docs/assets/make_deltas.py).
+
+## Citing
+
+If wvc is useful in your work, please cite the repository; GitHub's "Cite this repository" button reads [CITATION.cff](CITATION.cff).
+
+```bibtex
+@software{smith2026wvc,
+  author  = {Smith, Evan},
+  title   = {{wvc}: version control for open model weights},
+  year    = {2026},
+  url     = {https://github.com/evnsnclr/wvc},
+  license = {Apache-2.0}
+}
+```
+
+## Licence
+
+Apache-2.0; see [LICENSE](LICENSE). The models named here belong to their publishers; this repository includes none of their files.