Artifact [4a7a141eed]

Artifact 4a7a141eedfd7392fa773dfb2ab48307c7fc07452a5af7eb4d4c81ee11567997:

• File README.md — part of check-in [7f7828b7d6] at 2026-07-20 10:38:14 on branch trunk — README: point to the release notes, name the coverage step

  The limitations table stopped short of where a reader would look for more detail; it now points at the release notes rather than growing into a second copy of them. The named build steps were missing zig build cov, the kcov coverage report over the test suite. (user: dmestas, size: 4407) [annotate] [blame] [check-ins using]

# zit

[Fossil](https://fossil-scm.org)'s formats and sync protocol, reimplemented in
[Zig](https://ziglang.org) from their specifications.

zit is a library first — a Zig analog of libfossil: the delta encoding, the
artifact formats, derived repository state, and the HTTP sync protocol as a
clean, embeddable API. The `zit` binary is a thin CLI over that library.

The implementation is a direct port of four companion Internet-Drafts (frozen
reference copies in [`docs/rfcs/`](docs/rfcs/)):

| Module | RFC | What it specifies |
|--------|-----|-------------------|
| `delta` | `draft-fossil-delta-format-00` | byte-level delta encoding |
| `artifact` | `draft-fossil-artifact-format-00` | manifest / control-artifact card format, naming, checksums |
| `repostate` | `draft-fossil-repo-state-00` | derived branch / tag / leaf / current-trunk views |
| `sync` | `draft-fossil-sync-protocol-00` | HTTP sync / clone protocol |

Implementation follows the RFC dependency layering:

```
delta  ->  artifact  ->  repostate  ->  sync
```

## Design

The drafts are the authority, not Fossil's source. Test expectations come from
the spec text and its worked examples — every normative clause a module
implements gets a test citing its section. Fossil itself appears only in an
on-demand interop smoke check, which may confirm a spec-derived expectation but
never author one; a disagreement there means either zit misread the spec or the
spec is wrong, and the spec gets an erratum rather than the code a workaround.

No module touches ambient time, randomness, filesystem, or network; effects
arrive through injected interfaces. The sync client in particular is a pure
state machine — bytes in, bytes out — with transport supplied by the caller.
This keeps the library embeddable and makes the whole stack testable under
seeded deterministic simulation, where any failure replays exactly from its
seed.

## Scope

zit targets the **version-control substrate**: the check-in (manifest),
cluster, and tag/control artifact types. The collaboration types (wiki,
ticket, forum, attachment, technote) are carried opaquely — stored and
transported by hash, but not interpreted.

## Limitations in 0.1.0

The tracked bugs are closed, so what remains is deliberate: 0.1.0 is a
substrate, not a Fossil replacement. The gaps below are choices, not defects.

| Capability | Status in 0.1.0 |
|------------|-----------------|
| `diff` | Working-tree-versus-current-check-in only, and name-status only (`A`/`M`/`D`, sorted by path). No textual hunks, and no revision-to-revision diff — the two operands are always the working tree and its check-in. |
| Sync server code | A fixed informational placeholder (`0000000000000000`, sync §9.1) on both client and server — not a real per-server identity. The per-repository **project code** is not a placeholder: it is derived on `init`, persisted to config, emitted by `serve`, and adopted from the peer on `clone`. |
| `R` and `W` cards | Every manifest card letter is parsed and structurally validated (grammar, ordering, occurrence), but two are not interpreted: the `R` aggregate content checksum is retained and re-emitted verbatim when present, yet never generated on commit nor verified against content; the `W` wiki-text card rides on wiki artifacts, which are carried opaquely (see Scope) and never read. By contrast `T` (tag) cards drive the derived branch/tag/leaf state and `U` (user) is recorded on commit. |
| Verbs absent versus Fossil | No `stash`, `grep`, `ui`, or `settings`, and no revision-to-revision `diff`. |

See [`docs/RELEASE-NOTES-0.1.0.md`](docs/RELEASE-NOTES-0.1.0.md) for what shipped in this
release and what the conformance claim rests on.

## Build

Requires Zig 0.16+.

```sh
zig build            # build the `zit` binary into zig-out/bin/
zig build run -- version
zig build test       # run unit tests
```

Further named steps: `zig build dst` (deterministic simulation, `--seed N` to
replay), `zig build fuzz -- <target> --seed N` (seeded fuzz targets),
`zig build bench` (benchmarks), `zig build cov` (kcov coverage report over the
test suite), and `zig build smoke` (interop check against a `fossil` binary on
PATH; run manually at milestones, never part of `test`).

## Source control

This project is itself under Fossil. The repository lives in `.zit.fossil`
(ignored); open a checkout with `fossil open --keep .zit.fossil`.