22 KiB
rit — Enterprise Architecture
Scope of this document. The target enterprise shape for
rit: the full Git implementation as a multi-crate Rust workspace, the phased build order that maps thePLAN.mddeferred scope into crates, and the SDK/interop surface other Railyard apps (chieflyrithub) build on. This is a planning artifact — it does not change app code. Todayritis a single crate (src/{object,odb,oid,refs,repo,blob,tree,commit,tag,signature,headers,error}.rs, 35 tests incl. real-git interop againstgit2.50). The target below decomposes that core and lands the deferred scope (packfiles/delta, index/worktree, wire protocol v2, merge/rebase, SHA-256) as discrete crates behind a hard compatibility gate.
1. Design invariants (carried from PLAN.md)
These are non-negotiable and shape every crate boundary:
- Library-first. Every capability lives in a library crate; the CLI is a thin driver. No behavior is CLI-only.
- Real-git-compat gate. No compatibility claim ships without a named test.
Object ids are byte-identical to
git hash-object;git fsckaccepts what we write; every parser has a differential test against the referencegitCLI. The forge (rithub) is not built until theritcore passes interop, crash-recovery, parser-fuzzing, and concurrent-ref gates (PLAN "Initial customer and promise" + "Release sequence"). - Adversarial input. Repository data is hostile. Every parser is fail-closed,
bounded (the
MAX_OBJECT_SIZEcap andZlibDecoder::takeguard in today'sodb.rsare the template), and fuzzed. - Shared crates cannot depend on the forge, a UI, or a specific database (PLAN "Rust workspace architecture"). Storage APIs expose bounded streams, not "assume it fits in memory."
- Hash-agnostic core. The object model is generic over the hash so the SHA-1 → SHA-256 path is a type parameter, not a rewrite.
- Immutability. Objects are content-addressed and never mutated in place;
writes are atomic (temp file →
fsync→ rename, asOdb::writealready does).
2. Target workspace tree
The standalone rit package becomes a Cargo workspace (it keeps
[workspace] isolation from the desktop GPUI/Metal build, exactly like mint
and agent-runtime are excluded at the repo root). Crates use the rit- prefix;
the PLAN's git-* names are noted as aliases.
apps/rit/
Cargo.toml # [workspace] members = crates/*
rust-toolchain.toml # pinned MSRV (PLAN pre-code gate item 1)
README.md
PLAN.md # product + release plan (source of truth)
ARCHITECTURE.md # this document
deny.toml # cargo-deny: license/advisory gate
docs/
COMPATIBILITY.md # the frozen compat matrix (Stage 0 deliverable)
THREAT-MODEL.md # adversarial-input threat model (Stage 0)
RECOVERY.md # corruption/crash-recovery rules (Stage 0)
fixtures/ # licensed real-git repos for differential tests
crates/
rit-hash/ # [git-hash] hash abstraction: Sha1, Sha256,
# sha1dc collision detection, ObjectId<H>,
# hex, prefix. Everything else is generic
# over this so SHA-256 is a type param.
rit-object/ # [git-object] object model: ObjectType, loose
# framing "<type> <len>\0<payload>", canonical
# (de)serialization for blob/tree/commit/tag,
# validation. (today's object/blob/tree/
# commit/tag/signature/headers.rs)
rit-odb/ # [git-odb] object database: loose store (today's
# odb.rs) + packed store, quarantine dirs,
# alternates, streaming reads, fsck-grade
# verification. Facade over rit-pack + loose.
rit-pack/ # [git-pack] packfile + .idx parsing, ref/ofs
# delta resolution, thin-pack fixups, pack
# writing, reachability bitmaps, delta chain
# bounds. (PLAN deferred: packfiles/delta)
rit-refs/ # [git-refs] refs, symbolic refs, packed-refs
# (today's refs.rs) + reflogs, atomic
# compare-and-swap transactions, lock files,
# lock recovery, ref races.
rit-index/ # [git-index] index (staging) formats v2/3/4 +
# extensions (TREE, UNTR, sparse). (PLAN
# deferred: index/worktree)
rit-worktree/ # [git-worktree] checkout, status, add, restore,
# .gitignore rules, filesystem-safety adapters
# (path traversal, case-fold, symlink hazards).
rit-revision/ # [git-revision] rev syntax (HEAD~3, a..b, ^),
# graph walks, reachability, merge-base — the
# bounded walk in today's Repository::log,
# generalized.
rit-diff/ # [git-diff] Myers/histogram text diff, binary
# diff, rename/copy detection, hunk model.
rit-merge/ # [git-merge] merge bases, three-way merge,
# recursive/ort strategy, conflict model, the
# sequencer for rebase/cherry-pick/revert.
rit-protocol/ # [git-protocol] smart protocol v2, pkt-line,
# capability negotiation, upload-pack (fetch/
# clone) + receive-pack (push), quarantine of
# received objects. Transport-agnostic.
rit-transport/ # HTTP + SSH transport adapters for rit-protocol
# (client side): git-smart-HTTP, ssh exec.
rit-fsck/ # object/connectivity/reachability verification,
# corruption reporting — the read-only "is this
# repo sound?" pass used by Stage 1 + CI.
rit-repo/ # [porcelain] the Repository facade (today's
# repo.rs) tying odb+refs+index+worktree into
# init/add/commit/log/branch/checkout/merge.
rit-porcelain/ # high-level command semantics matching git's
# UX (status output, log formatting) — what the
# CLI and SDK both call.
rit-cli/ # [git-cli] the `rit` binary: thin clap driver
# over rit-porcelain (today's main.rs,
# hash-object/cat-file/ls-tree/log → grows to
# init/add/commit/branch/clone/fetch/push).
rit-sdk/ # the stable, semver'd public API surface other
# apps depend on (rithub, tooling). Re-exports
# a curated subset; hides crate churn.
rit-testkit/ # differential harness: shell out to real `git`,
# assert byte-equality (today's tests/interop.rs
# promoted to a reusable crate), fixture repos,
# property-test generators.
rit-fuzz/ # cargo-fuzz targets: every untrusted parser
# (loose, tree, commit, pack, idx, pkt-line,
# index, packed-refs) + protocol state machines.
Crate dependency graph (acyclic, leaf → root)
rit-hash
└─ rit-object
├─ rit-pack ──┐
├─ rit-odb ◄──┘ (odb is the facade over loose + pack)
├─ rit-refs
├─ rit-index
├─ rit-diff
├─ rit-revision (← odb, refs)
├─ rit-merge (← diff, revision, odb)
├─ rit-worktree (← odb, index, refs)
├─ rit-fsck (← odb, refs, revision)
└─ rit-protocol (← odb, refs, pack)
└─ rit-transport (HTTP/SSH)
rit-repo (← odb, refs, index, worktree, revision, merge, protocol)
rit-porcelain (← rit-repo)
rit-cli (← rit-porcelain) rit-sdk (← curated re-exports)
rit-testkit / rit-fuzz (dev-only, depend across the graph)
Boundary rules enforced by CI: rit-hash/rit-object depend on nothing
Railyard-specific; nothing below rit-repo knows about a CLI; no crate depends on
a database or on rithub. cargo-deny guards the license/advisory surface (PLAN
"Verification strategy").
3. Phased build order (maps PLAN Release Sequence → crates)
Each stage is gated: it does not start until the prior stage's named tests pass.
| Stage | PLAN name | Crates delivered / extended | Gate to exit |
|---|---|---|---|
| 0 | Specification & harness | rit-testkit, rit-fuzz, docs/{COMPATIBILITY,THREAT-MODEL,RECOVERY}.md, fixtures/ |
Compat matrix + threat model frozen; differential harness green on the existing 4 commands |
| 1 | Read-only core | Split today's crate into rit-hash rit-object rit-odb rit-refs rit-revision rit-repo rit-porcelain rit-cli; add rit-pack (read), rit-fsck |
cat-file/ls-tree/log/fsck on hostile repos never write outside the repo or use unbounded resources; pack reads interop-verified |
| 2 | Local authoring | rit-index, rit-worktree, rit-diff; extend rit-repo/rit-cli with init/status/add/restore/commit/branch/tag/reflog |
Crash tests pass for every state-changing command; index round-trips vs real git |
| 3 | Exchange | rit-protocol (upload-pack + receive-pack), rit-transport (HTTP+SSH), rit-pack (write/thin), quarantine in rit-odb |
clone/fetch/push interop with reference git client and server; atomic refs + quarantine + interrupted-transfer recovery proven |
| 4 | History editing | rit-merge (three-way, sequencer), rebase/cherry-pick/revert/conflict continue-abort in rit-repo/rit-cli |
Merge/rebase match documented git behavior; user work preserved across induced failures |
| 5→6 | Forge / public | No new rit crates — this is where rithub consumes rit-sdk. rit's SHA-256 repository format (rit-hash second hash) lands here as an explicit, separately-gated matrix entry. |
Security review; SHA-256 interop matrix; capacity + restore drills (owned by rithub) |
SHA-256 is intentionally not a late rewrite: rit-hash is generic from
Stage 1, so SHA-256 is a new hash implementation + a compat-matrix row, gated at
Stage 5/6 per PLAN ("explicit path to Git's SHA-256 repository format").
4. SDK / interop surface
rit-sdk is the only crate external consumers (rithub, internal tooling) are
allowed to depend on. It is semver-stable and hides the churn of the inner crates.
Rust API contract (the shape rithub builds on):
rit_sdk::Repository open / discover / init (today's Repository, widened)
.odb() -> Odb content-addressed object read/write, streaming
.refs() -> RefStore atomic CAS ref transactions, reflog, packed-refs
.index()/.worktree() staging + checkout (Stage 2+)
.revwalk(spec) bounded graph traversal / merge-base (rit-revision)
.diff(a, b)/.merge(...) (Stage 4)
rit_sdk::server upload_pack / receive_pack handlers over an
AsyncRead/AsyncWrite pair — the seam a forge mounts
behind smart-HTTP and SSH (Stage 3)
rit_sdk::ObjectId / Object / Signature canonical types, hash-generic
Wire/tooling interop (beyond the Rust API):
- Git wire protocol v2 —
rit-protocolspeaks the real thing, so any stockgitclient can clone/fetch/push against a server embeddingrit-sdk::server. This is the interop guarantee that lets rithub host real repos for real users. - On-disk format — the
.gitdirectoryritreads/writes is byte-compatible, so a rithub-hosted repo is inspectable by stockgitand vice-versa. ritCLI — a scriptable boundary for CI hooks and ops tooling.
5. Composability with the Railyard platform
rit is the core dependency of rithub: rithub adds no object storage, refs,
packfiles, protocol, or PR truth of its own — it path-depends on rit-sdk and
mounts rit-sdk::server behind its HTTP/SSH front doors (see
../rithub/ARCHITECTURE.md §"How rithub depends on
rit").
Honest fit with the rest of the rail:
ritis a developer/systems tool, not part of the AITP-402 payment rail. It has noMintdependency and settles no money. That separation is deliberate and correct — coupling repository correctness to a ledger would violate the PLAN security contract.- Provenance touch-points (opt-in, additive):
rit's content-addressed object ids and signed-commit/tag verification (rit-objectsignatures) are a natural anchor for provenance. A commit id can be referenced by a Mint hash-linked receipt or a context-passport version record so "this artifact was produced at commit<oid>" is verifiable — but that binding lives in the consumer (Passport/Mint), never insiderit.ritstays a pure Git core. - AITimeMachine may attach checkpoints to commit ids; again,
ritexposes the id, the consumer owns the mapping (PLAN "AITimeMachine … does not implement or replace Git").
6. Graph engineering layer
Git is a knowledge graph: the object database is a content-addressed DAG, and
refs are named roots over it. Modeling rit as a graph (per
~/.claude/skills/graph-engineering/references/modeling.md) makes the ontology
explicit and gives rit-fsck, rit-revision, and rithub's code-intelligence a
shared vocabulary.
6.1 Ontology (the object DAG)
Competency questions (the schema's spec + test suite):
- Which commits are reachable from ref
R? - What is the merge-base of commits
AandB? - Which blobs/trees does commit
Cintroduce vs. its parents? - Who authored, and who committed,
C, and when? - Which tag objects point (transitively) at commit
C? - Is object
Oreachable from any ref (i.e. safe from GC)?
Entities (canonical name = lowercase 40/64-hex object id; refs by full name):
| Entity | Definition | Backing type |
|---|---|---|
Blob |
file contents (a leaf) | rit-object::Blob |
Tree |
directory listing | rit-object::Tree |
Commit |
a history node | rit-object::Commit |
Tag |
annotated tag | rit-object::Tag |
Ref |
named mutable pointer (branch/tag/HEAD) | rit-refs::RefTarget |
Signature |
attribute-bearing author/committer identity (name, email, time, tz) | rit-object::Signature |
Relations (precise verbs, domain → range, with time + provenance):
| Relation | Domain → Range | Provenance / time carried |
|---|---|---|
HAS_PARENT |
Commit → Commit | ordered (first-parent); defines history edges |
HAS_TREE |
Commit → Tree | root tree of the snapshot |
CONTAINS |
Tree → {Tree, Blob} | entry name + mode as edge attrs |
POINTS_AT |
Ref → {Commit, Tag} | via reflog: who moved it, old→new oid, time |
TAGS |
Tag → {Commit, Tree, Blob, Tag} | tagger Signature |
AUTHORED / COMMITTED |
Signature → Commit | time + tz are the edge's timestamp |
Provenance is intrinsic here — it is not retrofitted metadata but the object bytes
themselves: author/committer signatures and reflog who/old/new/when lines are
the edge properties, and every id is a cryptographic content hash, so the graph is
tamper-evident by construction. This is exactly the "decide how every fact carries
time + provenance at modeling time" rule, satisfied for free by Git's design.
rit-revision is the query engine over this graph (reachability, merge-base,
a..b), and rit-fsck is the consistency checker (every edge's range object must
exist and hash-verify — connectivity). The bounded visited-set walk already in
Repository::log is the template: no unbounded graph walks on adversarial input.
6.2 Task graphs (fetch / push / merge)
Exchange and history-editing operations are naturally task graphs (per
task-graphs.md), and modeling them that way is what lets rit-protocol and
rit-odb parallelize safely without corrupting data.
Fetch/clone — the diamond. Negotiation produces a set of wanted objects that never read each other's bytes → the "delete fake edges" win: object/pack transfer fans out in parallel, then a mandatory separate verify node (quarantine) gates the merge into the live odb:
┌─ transfer pack slice 1 ─┐
negotiate ────┼─ transfer pack slice 2 ─┼─→ verify (fsck + connectivity, ─→ install
(wants/haves) └─ transfer pack slice 3 ─┘ in QUARANTINE odb) refs (CAS)
The verify node is non-negotiable (a peer's pack is adversarial input): delta chains resolved, every object hash-checked, connectivity proven — before any ref moves. This is quarantine, straight from PLAN's security contract.
Push — diamond + human/policy gate. Same parallel receive → quarantine verify, but the ref-update edge is irreversible on a shared repo, so it routes through an explicit gate:
receive-pack ─→ quarantine verify ─→ [POLICY/HUMAN GATE: protected-branch,
non-fast-forward, signed-commit, hooks]
─→ atomic CAS ref transaction (owned merge)
rit exposes the gate as a hook/policy seam; rithub supplies the human side
(branch protection, required reviews — see its task-graph section). One owner of
the ref merge (the atomic CAS transaction in rit-refs) — never two writers,
satisfying the "one writer per artifact" guardrail.
Merge — bounded diamond. merge-base (parallel ancestry walks from each tip) →
three-way content merge per path (parallelizable, independent files) → verify (no
conflict markers left / conflicts surfaced) → single sequencer owns the resulting
commit. The sequencer in rit-merge is the single merge-owner the stop rule
demands; every rebase/cherry-pick loop carries a max-round cap.
7. Enterprise scale estimate
The current rit is ~14 source files. That is the loose-object read slice, NOT
a complete Git. A complete Git implementation (packfiles + delta, index,
worktree, wire protocol v2, diff, merge/rebase, SHA-256) is hundreds of source
files and six figures of Rust. For calibration: libgit2 is ~100K LOC of C and
gitoxide (the mature Rust Git) spans ~30 crates and well over 200K lines. The
estimate below is sizing, not empty scaffolding — it exists so no one mistakes
today's slice for a finished product.
| Crate | ~Files | ~LOC | Notes |
|---|---|---|---|
| rit-hash | 3 | 800 | SHA-1, SHA-256, sha1dc, generic id |
| rit-object | 12 | 4,000 | (today's object/blob/tree/commit/tag lives here) |
| rit-odb | 8 | 3,500 | (today's odb.rs) + packed facade, quarantine, alternates |
| rit-pack | 20 | 12,000 | packfile/.idx, delta resolution, bitmaps, pack writing |
| rit-refs | 10 | 4,500 | (today's refs.rs) + reflog, CAS transactions, locks |
| rit-index | 12 | 6,000 | index v2/3/4 + extensions |
| rit-worktree | 15 | 8,000 | checkout, status, ignore, fs-safety adapters |
| rit-revision | 10 | 5,000 | rev syntax, graph walks, merge-base |
| rit-diff | 12 | 7,000 | Myers/histogram, rename/copy detection |
| rit-merge | 14 | 9,000 | three-way, ort strategy, sequencer |
| rit-protocol | 18 | 11,000 | v2, pkt-line, upload-pack, receive-pack |
| rit-transport | 10 | 5,000 | HTTP + SSH adapters |
| rit-fsck | 6 | 2,500 | object/connectivity verification |
| rit-repo | 12 | 6,000 | (today's repo.rs) widened to full porcelain |
| rit-porcelain | 20 | 9,000 | command semantics (status/log/diff formatting) |
| rit-cli | 25 | 6,000 | (today's main.rs) → one module per subcommand |
| rit-sdk | 4 | 1,200 | stable public surface |
| rit-testkit | 10 | 4,000 | (today's tests/interop.rs promoted) + fixtures |
| rit-fuzz | 12 | 2,000 | cargo-fuzz targets per parser |
| Total (src) | ~233 | ~106,500 | +tests/fixtures → ~300–400 files, ~150K LOC |
What "done" means per phase: Stage 1 (read-only core) ≈ 60–80 files. Stage 2
(local authoring) ≈ +80 files. Stage 3 (exchange) ≈ +70 files. Stage 4 (history
editing) ≈ +50 files. The current 14-file slice is ~5% of a complete rit and
corresponds to a portion of Stage 1. Declaring rit "done" at the loose-object
slice would be declaring Git done at cat-file.
8. Key decisions
- Workspace, not one crate — decompose along PLAN's crate lines so the deferred scope (pack/index/worktree/protocol/merge) lands as isolated, independently-testable, independently-fuzzed units.
rit-hashgeneric from day one — SHA-256 becomes a hash impl + a matrix row, never a rewrite.rit-sdkas the single stable seam — rithub and tooling depend only on the SDK, insulating them from inner-crate churn.- Compat gate is a release blocker, not a wish —
rit-testkit+rit-fuzz+ fixtures are Stage 0, and the forge cannot begin until the core gate is green. - No payment-rail coupling —
ritstays a systems tool; provenance ties are additive and owned by consumers (Mint/Passport), preserving the security contract.