Artifact [5ed8b4d35e]

Artifact 5ed8b4d35ee23b7990261f8af34f5fa3cc629baf63b0059d9f7bb2d2c48dc802:

• File docs/RELEASE-NOTES-0.1.0.md — part of check-in [07c840ae4b] at 2026-07-20 10:13:34 on branch trunk — Release notes: drop the CI-runner clause on the fossil version

  The notes named the fossil version smoke passed against, which is a legitimate conformance fact, but then explained CI runner provisioning and told a future editor to reconcile it against a workflow log. That is tooling detail with no place in a document meant to outlive the tooling. The fossil version stands alone as the fact that matters. (user: dmestas, size: 5307) [annotate] [blame] [check-ins using]

# zit 0.1.0

zit is Fossil's formats and sync protocol reimplemented in Zig from four
companion Internet-Drafts (frozen in [`docs/rfcs/`](rfcs/)). It is a library
first — the delta codec, the artifact formats, the derived repository state,
and the HTTP sync protocol as an embeddable API — with a thin CLI over the top.
This first tagged release is a working version-control substrate. It is honest
about what it does not yet do; the limitations below are deliberate, not bugs.

## What's implemented

- **Delta codec** — the byte-level delta encode/decode of
  `draft-fossil-delta-format-00`.
- **Artifact formats** — the manifest / control-artifact card grammar of
  `draft-fossil-artifact-format-00`: every card letter parsed, the §4.4/§4.5
  ordering and occurrence rules enforced, and the Z and R checksums modelled.
  The check-in (manifest), cluster, and tag/control types are interpreted; the
  collaboration types (wiki, ticket, forum, attachment, technote) are carried
  opaquely — stored and transported by hash, not read.
- **Derived repository state** — branch, tag, leaf, and current-trunk views of
  `draft-fossil-repo-state-00`, with tag propagation along the check-in DAG.
- **HTTP sync** — clone, pull, push, and bidirectional sync of
  `draft-fossil-sync-protocol-00`, driven by a pure client state machine
  (bytes in, bytes out) with transport supplied by the caller; plus a `serve`
  side that answers the framed protocol.
- **CLI** — the working-copy and history verbs (`init`, `add`, `rm`, `mv`,
  `status`, `stat`, `diff`, `extras`, `clean`, `addremove`, `commit`, `log`,
  `open`, `update`, `merge`, `revert`, `undo`, `redo`, `leaves`, `timeline`,
  `branch`, `tag`, `amend`, `info`, `ls`, `cat`, `artifact`, `annotate`,
  `bisect`), the sync verbs (`serve`, `clone`, `pull`, `push`, `sync`,
  `remote`), and store maintenance (`pack`). `open` honours
  `--manifest[=r,u,t]`; `-R` reads a repository with no working tree, and
  `-n` limits `timeline`/`log` to the most recent N as well as previewing
  the destructive verbs.

No module touches ambient time, randomness, filesystem, or network directly;
effects arrive through injected interfaces, so the whole stack replays exactly
under seeded deterministic simulation.

## What the conformance claim rests on

The drafts are the authority, not Fossil's source: test expectations come from
the spec text and its worked examples, and every normative clause a module
implements gets a test citing its section. That keeps the claim honest against
the *spec* — but a spec can be misread, so one step checks against the
reference implementation.

That step is `zig build smoke`. It drives the **real `fossil` binary** and is
the only step that proves conformance against Fossil itself rather than
against our own reading of the RFCs. A disagreement there means either zit
misread the spec or the spec is wrong — the spec gets an erratum, never the
code a workaround.

The exact fossil that smoke passed against matters, so name it:

> **fossil 2.28 [52445a27f1]** (2026-03-11)

## What's deliberately deferred, and where it's documented

- **`diff` is working-tree-versus-current-check-in only, and name-status
  only.** It emits `A`/`M`/`D` per path, no textual hunks, and there is no
  revision-to-revision diff. Documented in `zit diff --help`.
- **The sync *server code* is a fixed informational placeholder**
  (`0000000000000000`, sync §9.1) on both client and server. This is not a
  per-server identity. The per-repository *project code*, by contrast, is real:
  derived on `init`, persisted, emitted by `serve`, and adopted on `clone`.
  Documented at the `server_servercode` / `server_projectcode` definitions in
  `src/serve.zig`.
- **The `R` and `W` cards are parsed but not interpreted.** The `R` aggregate
  content checksum is retained and re-emitted verbatim when present, but is
  never generated on commit nor verified against content. The `W` wiki-text
  card belongs to wiki artifacts, a collaboration type carried opaquely. The
  opaque-carry boundary is documented in the README **Scope** section; the card
  grammar and per-type card masks live in `src/artifact.zig`.
- **Verbs absent versus Fossil:** no `stash`, `grep`, `ui`, or `settings`, and
  no revision-to-revision `diff`. The command set is documented in `zit help`.

## Storage

`zit pack` performs an at-rest re-deltification pass — fossil-style best-of-N
delta-base selection plus a monotonic-shrink guard that keeps the smaller of an
existing frame and its re-encoding, so repacking a clone of fossil-quality wire
deltas is a net win rather than a regression. It is at-rest only: all four RFCs
stay conformant and wire interop is preserved, and every repacked frame is
hash-verified against the log.

Measured whole-file, index-inclusive, in commit `bab9303056`:

| Repository | Before pack | After pack | Versus fossil |
|------------|-------------|------------|---------------|
| sqlite | 207.3 MB (1.40x) | 174.4 MB (1.18x) | fossil 147.7 MB |
| fossil-scm | 117.5 MB (1.63x) | 108.1 MB (1.50x) | fossil 72.2 MB |

## Build

Requires Zig 0.16+.

```sh
zig build            # build the zit binary into zig-out/bin/
zig build test       # unit tests
zig build smoke      # interop check against a fossil binary on PATH
```