zit

Fossil's formats and sync protocol, reimplemented in Zig 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/):

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 for what shipped in this release and what the conformance claim rests on.

Build

Requires Zig 0.16+.

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.