# zit — Handoff

Start-here document for anyone continuing the implementation. The scaffold is
in place, builds clean, and tests pass. Nothing of the actual VCS is
implemented yet beyond two foundational primitives.

## What this is

`zit` is a Fossil version-control system written in Zig — a **direct port from
the specifications**, not from Fossil's C source. The authority is the four
Internet-Drafts frozen in [`docs/rfcs/`](rfcs/) (`.txt`). Fossil's C source is
used only as an oracle for byte-exact verification, never copied.

## Current status

| Area | State |
|------|-------|
| Project scaffold, build, CLI | done — `zig build`, `zig build test`, `zig build run -- version` |
| `src/delta.zig` | base-64 int codec (MSB-first) + checksum (mod 2³²), with RFC-derived tests. `apply`/`create` stubbed. |
| `src/artifact.zig` | artifact naming (SHA-1/SHA3-256, lowercase hex) + Z-card MD5, with RFC example vectors. Card/type enums. `parse` stubbed. |
| `src/repostate.zig` | skeleton: `Rid`, `resolveName`, `currentTrunk` stubs with the governing rules in doc comments. |
| `src/sync.zig` | skeleton: `ClientState` (the §3.8 state machine), `Client.step` stub. |

Everything marked "stub" returns `error.NotImplemented` and cites the RFC
section that governs it.

## Layout

```
build.zig, build.zig.zon      Zig 0.16 build (module "zit" + exe "zit")
src/root.zig                  library root; re-exports the four modules + aggregates tests
src/main.zig                  CLI entry
src/{delta,artifact,repostate,sync}.zig   one module per RFC
docs/rfcs/*.txt               the four frozen RFC finals (reference)
docs/HANDOFF.md               this file
.zit.fossil                   the Fossil repository (ignored; not tracked)
```

## Build & test

Requires **Zig 0.16+**.

```sh
zig build                 # -> zig-out/bin/zit
zig build test            # unit tests
zig build run -- version
```

## Implementation approach

1. **Test-first, one RFC rule at a time.** Each rule becomes a test that cites
   its section, then the code to make it pass.
2. **Verify against the reference where a byte-exact check exists.** fossil 2.28
   is on PATH (`/opt/homebrew/bin/fossil`). The RFC examples were themselves
   re-captured from it; you can reproduce a manifest with
   `fossil commit --user-override <u> --date-override <d> ...` then
   `fossil artifact current` and compare bytes. The delta checksum and the
   SHA3/MD5 vectors in the current tests came from that reference.
3. **Layer order:** `delta -> artifact -> repostate -> sync`. Don't start a
   layer before the one it depends on is real.

## Suggested next steps (in order)

1. **delta.apply** (RFC §4) — the decoder: parse header, copy/literal segments,
   trailer; enforce the enumerated rejection conditions; verify the checksum.
   This is the smallest self-contained deliverable and fully testable.
2. **delta.create** (RFC §3, §5) — the encoder.
3. **artifact.parse** (RFC §4, §5) — card tokenizer, ordering rules, per-type
   validity, Z/R verification, delta-manifest reconstruction (RFC §"Delta
   Manifest Reconstruction").
4. **repostate** (RFC §3–§9) — DAG build, crosslink, tag propagation, leaves,
   symbolic-name resolution (pure max-`mtime`).
5. **sync** (RFC §3–§11) — the client state machine, round dispatch, phantom
   resolution, clone, auth, config.

## Scope

Version-control substrate only: **check-in (manifest), cluster, tag/control**
artifact types; cards `B C D F M N P Q R T U Z`. The collaboration types
(wiki, ticket, forum, attachment, technote — cards `A E G H I J K L W`) are
**carried opaquely** (stored/transported by hash, not interpreted). This is a
deliberate scope decision; the RFCs still describe the full set.

## Fossil workflow

The repo lives in `.zit.fossil` inside the tree (ignored via
`.fossil-settings/ignore-glob`). To work with a fresh clone of the directory:

```sh
fossil open --keep .zit.fossil    # establish a checkout without touching files
fossil status
fossil commit -m "..."            # commits land on trunk
```

Standard fossil: `fossil timeline`, `fossil diff`, `fossil branch new`, etc.

## Zig 0.16 notes (things that changed and cost time)

- `main`'s signature is `pub fn main(init: std.process.Init) !void`.
- Command-line args: `try init.minimal.args.toSlice(arena)` (there is no
  `std.process.argsAlloc`/`argsWithAllocator`).
- stdout is via the new I/O interface:
  `var w: std.Io.File.Writer = .init(.stdout(), init.io, &buf);` then
  `w.interface.writeAll(...)` and `w.interface.flush()`.
- Test aggregation: `std.testing.refAllDeclsRecursive` is gone; instead a
  `test { _ = @import("delta.zig"); ... }` block in `root.zig` pulls each
  module's tests into the library test binary.
- `build.zig.zon` requires a `.fingerprint`; `zig build` prints the value to
  add if it is missing.

## References

- `docs/rfcs/draft-fossil-delta-format-00.txt`
- `docs/rfcs/draft-fossil-artifact-format-00.txt`
- `docs/rfcs/draft-fossil-repo-state-00.txt`
- `docs/rfcs/draft-fossil-sync-protocol-00.txt`
- Reference implementation for byte-exact checks: fossil 2.28
  (`fossil version`).