Specification
Formats, algorithms and invariants of Zit 0.1.
Normative for version 0.1. The reasons behind each part are recorded as architecture decision records (ADR 1 to ADR 17) in the adr/ folder of the repository. Each rule names the test that enforces it where one exists.
1. Objects
1.1 State
A git tree object. state id = tree id.
1.2 Change
A git commit object.
| Commit field | Meaning |
|---|---|
| tree | resulting state |
| parents | changes built on. First parent: the base. Second parent, if any: a change composed in |
| author name | agent |
| message | intent, then the author’s account, then trailers |
Trailers, one per line, after the intent:
Zit-Agent: <name>
Zit-Session: <id> (optional)
Zit-Read: <resource> (zero or more)
Zit-Tokens: <in> in, <out> out (optional: what the agent reported)
Zit-Cost-USD: <dollars> (optional)
Zit-Change: <commit id> (on a linear compose: the change it lands)
Every trailer value is one line: control characters are dropped, newline and tab become a space, so an agent name, session id or declared read cannot end the trailer and start another. In the intent and account, a line starting with Zit- is indented by one space so it is not read back as a trailer. (a_declared_read_cannot_forge_a_trailer, a_session_id_cannot_forge_a_trailer)
A linear compose carries the Zit-Read trailers of every change it lands, and one Zit-Change per change; the trailers on base..current are how Zit tells that a change, or an ancestor of it, landed linearly. (a_linear_compose_keeps_the_declared_reads_of_the_change, a_linear_accept_of_a_chain_tip_accepts_the_chain)
The committer is the person running Zit (user.name, user.email), and the commit is signed when commit.gpgsign is set. (tests/teams.rs, tests/usage.rs)
The first paragraph of the message is the intent; any further paragraphs before the trailers are the account: what the author reported doing and why (summary). A commit with no trailers is a valid change: agent = author name, intent = subject, account = body, no declared reads. (a_plain_git_commit_is_a_change)
1.3 Resource
resource = path ; whole file
| path "#" name ; top-level symbol
| path "#" type "::" m ; a method of a type
| path "#(imports)" ; the file's imports
| path "#" ; module-level code outside symbols
The path is everything before the first #; in it, a literal # is written %23 and % is written %25. (hashes_in_paths_and_names_round_trip)
Two resources overlap iff they are equal, or one is a whole file and both have the same path. For claims only, a type also holds its methods (T and T::m).
1.4 Evidence
A JSON blob:
{ "check": "ui", "key": "9f2c…", "state": "<tree id>", "passed": true,
"exit_code": 0, "duration_ms": 412, "output": "<last 4000 bytes>", "at": 1791025806 }
key = sha256(name NUL run NUL inputs)[..16 hex], where inputs is, for each declared input path in sorted order, path NUL "<mode> <type> <object id>" NUL as printed by git ls-tree, or path NUL "-" NUL if absent. Input paths are normalised first (./ui/ is ui); a path containing .. is an error. With no declared inputs, inputs is the state id. (input_paths_are_normalised_before_they_are_looked_up)
2. Refs
| Ref | Value | Written by |
|---|---|---|
refs/zit/current |
commit | init, accept |
refs/zit/changes/<commit id> |
commit | record; deleted by accept, discard |
refs/zit/evidence/<key> |
blob | check, accept |
refs/zit/logs/<commit id> |
blob: the last 64 KB of the agent’s stdout and stderr | run --log; not deleted by discard |
Fresh evidence from an accept is published in the same update-ref transaction that moves current; if the move loses the race, the evidence is written alone and the accept retried.
A clone trusts only the evidence it produced, listed in <git dir>/zit/evidence-produced/<key>, unless git config zit.trustFetchedEvidence true. A fresh result with the same verdict as an existing ref keeps the existing object. (tests/replicate.rs)
Invariant. refs/zit/current only moves by compare-and-swap from the value the accepting process observed. (racing_accepts_all_land_exactly_once)
3. Footprint
footprint(base, tip):
git diff-tree -r -z -M base tip(renames at git’s default 50% similarity; copies are not detected).renames= theold → newpairs.- For each changed path, index the old and new blob into units: top-level symbols and methods (
Type::method), the imports ((imports)), and everything else (path#). Each unit has a hash of its text, a hash of its interface (its text without function bodies and comments, including comments inside a type that has methods), and the identifiers it mentions. Attributes and comments directly above an item belong to it. For a renamed path the old blob is indexed under the old path and the new under the new; the units are compared across the pair. writes= units whose hash differs, added or removed;pathif either side has no grammar, is not UTF-8, is not a regular file, or exceeds 1 MiB. Across a rename, a changed or added unit is written at the new path, a dropped unit at the old path, an unchanged unit at neither.signatures= the written units whose interface hash differs.refs= identifiers mentioned by the new version of each written unit, excluding the identifier that declares it, and excluding members of values (x.get); members of imported modules (lib.price) count.reads= everyZit-Readof the commits inbase..tip; for a single-parent span, the change’s own.
conflicts(mine, theirs): for each resource w in theirs.writes: write-write if it overlaps one of mine.writes; else read-write if it overlaps one of mine.reads, or if w is in theirs.signatures and mine.refs names it (its name, or for T::m, its type T). Symmetrically, write-read. Writes at a renamed path are mapped to the base path before comparison, so old#sym and new#sym are the same resource to the other side. At accept, write-write on prose (Markdown) and on (imports) is left to the text merge; on generated paths it is ignored. (tests/renames.rs)
Footprints are cached under cache/footprint-v3/<base>-<tip>.json, declared reads under reads.json. (The directory name changes with the symbol rules.)
Symbol naming:
| Language | Symbols | Methods, as Type::method |
|---|---|---|
| Rust | every top-level *_item, macro_rules!; an impl block’s header joins its type, named from the parse tree (impl Tr for &'a Foo is Foo) |
functions in impl blocks |
| Python | def, class, decorated definitions, NAME = … |
functions in a class body |
| JavaScript, TypeScript, TSX | function, class, interface, type, enum, const/let/var declarators, declare …, namespace N {}, overload signatures, and their exported forms |
method_definitions, abstract method signatures and overload signatures in a class body |
| Go | func, type, const, var |
methods, by receiver type (*Stack[T, U] is Stack) |
| Java | class, interface, enum, record, @interface; the package line is path# |
methods and constructors |
| Ruby | class, module, top-level def and def self.x, top-level CONST; require, require_relative, load are (imports) |
def inside a class or module |
| C# | class, interface, struct, record, enum, delegate; using is (imports); a block namespace is not a unit (its declarations are top level, its name path#); a file-scoped namespace is path# |
methods and constructors, including expression-bodied |
| Markdown | each heading’s section, named by the heading text | — |
| TOML | each top-level table or key (Cargo.toml#package, #dependencies; [profile.release] is under #profile, [[bin]] under #bin) |
— |
| JSON | each top-level key of an object (package.json#scripts); a non-object document is one unit, path# |
— |
Markdown sections have no references. Text before the first heading is path#; an empty heading does not start a section. Manifest units are hashed from the parsed value re-serialised, so formatting, key order and comments are not content, and they have no references; a manifest that does not parse is one resource.
4. Accept
footprints conflict compares footprint(merge-base, change) with footprint(merge-base, current), then drops conflicts on paths declared as [[derive]] by the merged tree’s zit.toml and write-write conflicts on Markdown files and on (imports). git merge-tree clean? ignores conflicts inside [[derive]] paths. (ADR 12; dropping_a_derive_rule_brings_its_conflicts_back)
merged files parse?: every file both sides changed since the merge base, in a language with a grammar, is parsed in current’s, the change’s and the merged version; merged text with syntax errors neither side had rejects the change. Files are parsed whole. ([accept] parse_check, default on)
When an ancestor of the change landed linearly (a Zit-Change trailer on base..current names it), the merge base is that ancestor’s tree: staleness compares footprint(ancestor, change) with footprint(landing commit, current), and the text merge uses the ancestor’s tree as base through three throwaway deterministic commits (git 2.38 has no merge-tree --merge-base). (a_change_built_on_a_linearly_landed_change_is_not_stale_against_it)
Batch. accept A B C and accept --batch (every change whose status is verified, in status order) run the flow above per change with the candidate state as “current”, skipping a change that is already accepted, stale, does not merge, does not parse or fails to derive, then run the checks once on the combined state and move current once by compare-and-swap; if current moved, the whole batch is recomputed. A failing check rejects the batch. Each change keeps its own commit (a compose commit, or one Zit-Change commit under --linear). (tests/accept.rs)
Dry run. accept --dry-run runs the flow up to run checks and reports the checks that would run against those with evidence; [[derive]] is not run.
4.1 zit.toml
| Key | Meaning |
|---|---|
[[check]] name, run, inputs |
a check; see zit.toml |
[[check]] timeout |
seconds before the check is stopped and failed; default 1800 |
[[check]] serial |
run alone, whatever jobs allows; default false |
[[derive]] path, run |
a generated file, rebuilt on compose |
[prepare] run, inputs |
dependency install, run in the cached checkout, keyed by inputs |
ignore |
extra gitignore patterns for every workspace |
[accept] linear |
compose without merge commits |
[accept] parse_check |
refuse a composed state whose files no longer parse; default true |
[accept] jobs |
checks of one verification that may run at once; default 1 |
[workspace] stable_paths |
materialise into reusable slots ws/slot-N; default false |
Unknown keys are an error. An inputs entry containing a glob character is an error (input src/*.rs is a pattern; inputs are paths). The config is read from the state being acted on: at accept, checks come from current and from the composed state, derive from the composed state, and [accept] from current; prepare, ignore and [workspace] from the materialised state.
Git configuration Zit reads:
| Key | Meaning |
|---|---|
zit.trustFetchedEvidence |
trust evidence this clone did not produce |
zit.minFreeMB |
free space required on the volume holding Zit’s home before a workspace or view is built; default 512, 0 or negative disables |
zit.stablePaths |
same as [workspace] stable_paths = true, for this clone |
5. Workspace
Directory $ZIT_HOME/<repo>-<hash>/ws/<id>/, described in ADR 5; with stable paths, ws/slot-N, the lowest slot not in use, whose tree/ and git/ survive disposal (meta.json becomes retired.json) and are reset for the next occupant. meta.json holds id, base, base_state, merge_parent, intent, agent, session, created, pid, pid_started (the owner’s process start time: macOS proc_pidinfo, Linux /proc/<pid>/stat field 22; absent in older files), port (a TCP port on 127.0.0.1 free at materialisation) and path. zit run holds an exclusive lock on ws/<id>/run.lock while it runs; running(ws) probes it, retrying for up to 250 ms. A workspace’s owner is alive when its pid exists and, when both are known, its start time matches. record:
git add -Aandgit write-treeinside the workspace view.- If the tree equals the base state and no compose parent is set: nothing to record.
- Otherwise create the commit, create
refs/zit/changes/<id>, and re-base the workspace onto the new change.
.gitignore applies: ignored files are not part of the state. (ignored_files_are_not_part_of_the_state) So do the user’s global excludes, built-in by-product patterns and zit.toml ignore, through git/zit-ignore. (tool_byproducts_are_never_recorded)
Materialising: clone the cached checkout of the state (or the newest cached checkout, moved to the state with read-tree -m -u, which keeps ignored files). If [prepare] is declared and the checkout’s .zit-prepared key differs, run it; it must leave diff-files and untracked files empty. Publish the result to the cache when it is a new state of current, a first checkout, or newly prepared. (tests/prepare.rs)
5.1 Claims
claim(workspace, resources), under one lock:
- Held = for every other open workspace, its claims and its in-flight writes; for every speculative change, its writes.
[[derive]]paths are never held. In-flight writes are reused for up to 2 seconds per workspace (inflight.json, keyed by base) and computed before the lock. - If any requested resource overlaps anything held: refused, nothing recorded, the holders returned.
- Otherwise the resources are appended to the workspace’s
claimsfile.
In-flight writes are footprint(base state, snapshot), where the snapshot is taken with a temporary index so the workspace’s own index is untouched. (tests/claims.rs)
5.2 Verification views
$ZIT_HOME/<repo>-<hash>/verify/<n>/, n in 0..8, each guarded by an exclusive lock on <n>.lock. Moving a view to a change: git reset --hard <change>, git clean -fd, empty its tmp/. (ADR 10) Before every check after the first, the view is restored the same way (ignored files kept), so each check sees the state. (a_check_sees_the_state_not_what_an_earlier_check_wrote) Up to [accept] jobs checks run at once in the view, in declared order; a serial check waits for the others and runs alone. Verdicts are reported in declared order and jobs is not part of an evidence key.
5.3 Status memo
$ZIT_HOME/<repo>-<hash>/cache/status/<change id>: {current, evidence, status}, where evidence is a hash of the evidence ref names and ids, the ledger’s names and zit.trustFetchedEvidence. status reuses the memo only when both current and evidence match; an error status is never memoised. Written whole, then renamed. (tests/status.rs)
6. Interfaces
6.0 Names
The command is zit; git-zit is the same program for git zit …. Refs are under refs/zit/, change trailers are Zit-Agent, Zit-Session, Zit-Read, Zit-Tokens, Zit-Cost-USD, Zit-Change, the config is zit.toml, local state is in $ZIT_HOME (default ~/.zit).
6.1 CLI exit codes
| Code | Meaning |
|---|---|
| 0 | done |
| 1 | a negative answer: accept rejected, a check failed, a claim refused |
| 2 | an error: not a repository, not initialised, unknown id, bad usage |
| 124 | zit run --timeout expired |
| other | zit run: the agent’s exit code, or 128 + signal |
Every command accepts --json. Under --json, a failure is {"error": "<message>"} on stdout, the message on stderr, exit 2. (an_error_under_json_is_json) The reports of status, show, log, diff and doctor carry "schema": 1 at the top level; the number changes when a field changes meaning or is removed, not when one is added. Error messages never print git’s --git-dir, --work-tree or -c arguments.
6.2 Environment
| Variable | Effect |
|---|---|
ZIT_HOME |
where workspaces and caches live (default ~/.zit); a relative path is resolved against the working directory; empty means unset |
ZIT_GIT |
git binary (default git); named in the error when it cannot run |
ZIT_MATERIALISE=checkout |
disable copy-on-write clones |
ZIT_AGENT |
default agent name |
ZIT_WORKSPACE |
set by zit run for the agent; default workspace for record, read and claim |
TMPDIR |
set for agents and checks: a private directory inside the workspace’s directory |
ZIT_SUMMARY_FILE |
set by zit run: where the agent may write its account; otherwise the end of its output is used |
ZIT_INTENT_FILE |
set by zit run: <ws>/intent.txt; non-blank content becomes the recorded intent instead of --intent. {ZIT_INTENT_FILE} in the command is replaced by the path |
ZIT_PORT |
set for agents and checks: the workspace’s or view’s port, from meta.json |
ZIT_GH |
the GitHub CLI used by export --pr and probed by doctor; default gh |
ZIT_CACHE_DIR |
set for agents and checks: $ZIT_HOME/<repo>-<hash>/shared |
ZIT_TRACE |
print each git call and its duration to stderr (batch read sessions excluded), and workspaces whose edits cannot be seen |
ZIT_CHANGE, ZIT_STATE |
set for check commands |
6.3 MCP tools
zit_materialise, zit_claim, zit_read, zit_record, zit_status, zit_show, zit_log, zit_diff, zit_check, zit_retry, zit_dispose; with --integrator, also zit_accept and zit_discard. Arguments and results are the CLI’s --json shapes. A tool failure is a result with isError: true (a resources argument that is not a list of strings is one); an unknown tool or method is a JSON-RPC error -32601. A line that is not JSON or not UTF-8 is answered with -32700 and the server continues; a message that is not a request object with -32600; a batch is answered as a batch, an empty one with -32600, one of notifications only with nothing. (tests/mcp.rs, tests/hostile.rs)
6.4 Web view
zit web serves, on the loopback interface, to Host: localhost|127.0.0.1|[::1] only, GET only:
| Path | Returns |
|---|---|
/ |
the page |
/api/graph |
{repo, current, mainline: [change…], changes: [change + status + fork + wrote…], workspaces: [workspace + dirty + writes + claims + overlaps + fork…], totals: {changes, input_tokens, output_tokens, cost_usd}} |
/api/change/<id> |
the show --json shape plus diff (as zit diff prints it) |
/fonts/autohand-sans.woff2, /fonts/autohand-mono.woff2 |
the page’s fonts |
(tests/web.rs)
6.5 Rust library
cargo doc --open. The modules are the primitives: git (store), change, footprint, resource, symbols, workspace, claim, evidence, accept, clean, plus api (the shapes every interface returns), view, run, mcp, tui and web.