Artifact [67bb1afa5b]

Artifact 67bb1afa5bff033e7ce51ff92e782a8a22a5e64541c219b338147da4b1ad8f47:

• File README.md — part of check-in [a469147254] at 2026-07-25 14:51:11 on branch trunk — Release zit 0.1.3

  A serving release over 0.1.2. Where 0.1.2 made a large repository cloneable, 0.1.3 makes serving one fast and lean.

  A server against a large repository comes up immediately: the listener opens before the repository is read, so a client queues in the accept backlog while the server primes rather than being refused during a startup a large store made long. A push no longer stalls inside its own reply deadline; the snapshot rebuild it triggers now runs between connections. Serving reads the repository through an on-demand log-offset index rather than a resident copy, so peak memory to serve a 67,499-artifact repository fell from about 157 MB to about 32 MB, with clones byte-identical to before.

  Also: the end-to-end suite is safe to run concurrently with itself (fresh loopback ports), and the unclassifiable-artifact tolerance rule is now covered by deterministic simulation and an end-to-end scenario. (user: dmestas, size: 4473) [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.3.md`](docs/RELEASE-NOTES-0.1.3.md) for what shipped in this
release, and [`docs/RELEASE-NOTES-0.1.0.md`](docs/RELEASE-NOTES-0.1.0.md) for 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`.