OpenAgents

Code

docs/2026-08-24-walgit-forge-architecture-comparison.md

58e6347eeb72 · 53 KB

walgit and the forge: two implementations of one architecture

Date: 2026-08-24

Subject: walgit at commit 8e3ece5 ("walgit: initial public release", 68,231 lines of Rust across eight crates) compared with OpenAgents.Forge at commit b5eb4ee (15,519 lines of Elixir across 55 modules in lib/openagents/forge/).

Question: Both systems put a write-ahead log in object storage, make it the only ref authority, and treat every node's disk as a cache. What did each build on top of that, what does the other's shape reveal, and where does walgit's design expose a weakness in ours?

Method: direct reading of both implementations.

On our side: lib/openagents/forge/ — chiefly wal.ex, wal/gcs.ex, wal/local.ex, sync.ex, pushes.ex, git_http.ex, git_plane.ex, verification.ex, independence.ex, janitor.ex, receipt_repository.ex, anchor.ex — plus INVARIANTS.md (REPOSITORY-002, REPOSITORY-003, EXIT-001 through EXIT-006), the disclosure in docs/forge-operator-independence.md and docs/forge-exit-rehearsals.md, and the audits in docs/2026-08-21-repository-storage-architecture-audit.md, docs/2026-08-23-forge-wal-anchoring.md, and docs/2026-08-23-invariant-proof-audit.md.

On walgit's side: its Rust crates, protobuf schema, and simulation tests, with its README.md, AGENTS.md, GOAL.md, and docs/ read second so that intent never stood in for implementation.

Status: Comparison only. No implementation changed. Follow-ups in section 7 are proposals, not decisions.

0. How to read the citations

Paths in code font that begin lib/, test/, ops/, config/, docs/, or infra/ are this repository. Every other path — anything under crates/, web/, or a walgit-relative docs/ name given as "walgit's docs/…" — belongs to the walgit repository at commit 8e3ece5, which is a read-only reference clone and not part of this repository's history.

One word collides. docs/taxonomy.md defines checkpoint as a proposed save point in a thread, linked to a forge commit. walgit's checkpoint is something else entirely: a folded snapshot of a repository's log. This document says log checkpoint for walgit's object and never uses the bare word for it.

1. What the two systems share

Tobi Lütke published walgit over a weekend as a single Rust binary that hosts Git repositories in front of an S3 or GCS bucket with no database, no leader, and no local state that matters. It is an implementation of the architecture Cursor described in Git at any scale, whose system is called Continuity; walgit keeps that post verbatim in its docs/reference/cursor-git-at-any-scale.md.

Our forge is the same architecture, reached independently and written in Elixir. The agreement is at the level of mechanism, not vocabulary, and it holds on six points.

The log in object storage is the only ref authority; disks are caches. lib/openagents/forge/wal.ex:5 states it in the first sentence of the moduledoc: "The WAL in object storage is the source of truth for git refs; node disks are only a cache." walgit's GOAL.md states the same thing as its first numbered goal, and its AGENTS.md principle I asks of every change, "If every instance is wiped now, what is lost?" — the required answer being "warmth". lib/openagents/forge/sync.ex:4 is the same claim from the reader's side: "the bare repo on disk is a projection of the WAL, never authority."

A compare-and-swap on one small document is the only commit point, and it is the consensus. Our CAS is a GCS generation precondition: cas_index/3 uploads the index with ifGenerationMatch, and GCS itself rejects a stale write with a 412 that maps to {:error, :cas_conflict} (lib/openagents/forge/wal/gcs.ex:46, :65). walgit's is the same primitive on manifest.pb through its own ObjectStore trait, with PutMode::Create for the first write and a version token afterwards. Neither system elects anything. Both accept a push on any node, and both let the CAS decide which one wins. lib/openagents/forge/wal.ex:8 puts it exactly: "Because the index CAS serializes all pushes, two nodes can never both believe they advanced the same ref."

A push is acknowledged only after the log accepts it. lib/openagents/forge/pushes.ex:2 names the rule and its source in the same breath: "apply locally, persist to the WAL, and only then ack — 'we never acknowledge a push until it has been fully persisted.'" If the log refuses the entry, local refs are rolled back and the client sees a failed push (lib/openagents/forge/pushes.ex:114). walgit's AGENTS.md §2.2 ends its write path with "Never ACK before the bucket ACKs."

A losing writer refetches and retries rather than failing. lib/openagents/forge/pushes.ex:104 re-synchronizes and retries once on :cas_conflict. walgit refetches on a 412, re-validates every ref's old value, re-sequences, and retries with jittered backoff.

Both wrap the stock git binary rather than reimplementing pack logic. lib/openagents/forge/git_http.ex:3 credits the source of the idea directly: "wrapping the stock git binary ('Spokes got that exactly right' — standard packfiles, upstream clients, no custom object format)". walgit's decision D2 keeps upstream git for delta-compressing repack, bitmaps, bundle creation, and normal upload-pack, and admits gix only where it is measured faster and correct.

A node that has never seen a repository materializes it from the log. Ours replays entries onto an empty bare repository and can rebuild from sequence zero (lib/openagents/forge/sync.ex:73, and INVARIANTS.md, REPOSITORY-003). walgit loads the log checkpoint's ref snapshot and replays the tail above it.

That is a real convergence, and it is the reason the rest of this document is worth writing. The two systems then diverge almost completely, because they were built to answer different questions.

2. Feature by feature

Every row cites where the claim was checked. A walgit row was checked in its Rust sources, its protobuf schema, or its tests; where its own documentation says something the code does not do, the row says so.

Capability walgit Verified at Forge Verified at
Ref authority WAL in an S3 or GCS bucket crates/walgit-proto/proto/walgit/v1/wal.proto:27 WAL in a GCS bucket lib/openagents/forge/wal.ex:5
Commit point CAS on manifest.pb crates/walgit-wal/src/publish.rs:1067 CAS on the index by GCS generation lib/openagents/forge/wal/gcs.ex:46
Acknowledgment order Bucket first, then the client walgit's AGENTS.md §2.2 Bucket first, then the client; refs roll back otherwise lib/openagents/forge/pushes.ex:114
Pack handling Stock git for repack, bitmaps, bundles, and upload-pack by default crates/walgit-git/src/lib.rs:2445 Stock git for every service lib/openagents/forge/git_http.ex:559
Smart HTTP v0 Yes, always through the stock git subprocess crates/walgit-server/src/smart.rs:768 Yes lib/openagents/forge/git_http.ex:57
Protocol v2 Implemented in walgit: capabilities, ls-refs with prefixes, fetch, object-info, bundle-uri crates/walgit-server/src/smart.rs:139, :202 Available by delegation: GIT_PROTOCOL is passed to the stock binary, which negotiates v2 lib/openagents/forge/git_http.ex:554, :68
Log entry payload Content-addressed packfile with .idx, and .rev/.bitmap/.commit-graph side files crates/walgit-proto/proto/walgit/v1/wal.proto:96 The raw receive-pack request body, or a git bundle, or a ref-only record lib/openagents/forge/sync.ex:346
Log checkpoints Yes: folded ref snapshot plus pack inventory, on 256 entries, an 8 MiB tail, or one hour crates/walgit-wal/src/checkpoint.rs:38, :172 None absent from lib/openagents/forge/
Compaction Geometric fold published as a COMPACT entry; replicas download the result crates/walgit-server/src/ops.rs:673, crates/walgit-wal/src/publish.rs:1000 None absent from lib/openagents/forge/
Index or manifest growth Bounded: head pointer, checkpoint pointer, live pack set, log segment pointers crates/walgit-proto/proto/walgit/v1/wal.proto:27 Unbounded: the full entry list with each entry's whole ref map lib/openagents/forge/wal.ex:12, :335
Read freshness One conditional GET, 304 to serve locally, optional freshness window walgit's docs/ROUNDTRIPS.md §2 Two unconditional GET requests plus the whole index body, every read lib/openagents/forge/wal/gcs.ex:37, :251
Round-trip budget Pinned by test: push 5, warm refs 1, cold refs 2, checkpoint 4 crates/walgit-server/tests/sim.rs:1645 None absent from test/
Serving refs without objects Yes: refs sync level writes refs offline before packs exist crates/walgit-wal/src/sync.rs:929 No: the advertisement runs git upload-pack --advertise-refs on the local bare repository lib/openagents/forge/git_http.ex:68
Repository larger than the node Served: remote reader over 1 MiB range reads with a block LRU crates/walgit-wal/src/remote.rs:28, :82 Not served, and not refused early either no counterpart to check_fits
bundle-uri Yes: calendar slots, weekly full plus chained dailies and hourlies, two lists, blobless family crates/walgit-bundle/src/schedule.rs:19, crates/walgit-bundle/src/render.rs:117 None; git bundle is used only as an internal entry payload lib/openagents/repositories/importer.ex:328, lib/openagents/forge/git_plane.ex:553
Git LFS Batch API, objects in the bucket, optional read-through from an upstream walgit's docs/LFS.md; crates/walgit-server LFS routes None. Import copies pointer files and warns lib/openagents/github.ex:125, lib/openagents_web/live/repository_import_live.ex:121
Push policy Per-repository rule language at policy.json: protected refs, groups, fast-forward only, bypass walgit's docs/POLICY.md; decision D16 Protected branches bind assignment credentials only; any other write principal may move any ref lib/openagents/forge/git_http.ex:284, :299
Placement Configured serve and maintain globs; unplaced object work answers 503 with Retry-After walgit's AGENTS.md D30 Every connected node warms every repository lib/openagents/forge/sync.ex:43
Cross-instance mutex CAS lease with TTL at leases/<name>.pb, used for compaction and bundle builds crates/walgit-store/src/coord.rs:298, crates/walgit-server/src/ops.rs:735 Node-local :global.trans only; nothing coordinates across nodes but the CAS lib/openagents/forge/sync.ex:101
Maintenance loop One bounded unit per pass in priority order: checkpoint, repair, bundles, compaction, reverse index, fsck crates/walgit-server/src/maintain.rs:271, :396 Cache retention and receipt re-derivation; never touches the WAL lib/openagents/forge/janitor.ex:15, :53
Connectivity audit git fsck --connectivity-only every 7 days, report at fsck.pb, gated on the pack set fitting locally crates/walgit-server/src/ops.rs:217, crates/walgit-server/src/maintain.rs:400 On demand: Verification.verify/2 walks rev-list --objects over exportable refs lib/openagents/forge/verification.ex:29
Automatic repair Fetches missing objects from upstream.git and publishes them; nothing happens without an upstream crates/walgit-git/src/repair.rs:74, crates/walgit-server/src/maintain.rs:286 Rebuild from sequence zero; the recovery path is forbidden from consulting the mirror lib/openagents/forge/sync.ex:255, INVARIANTS.md EXIT-003
Shallow state None on the server; a shallow-seeded repository is a repository with missing objects crates/walgit-git/src/receive.rs:95; no graft in crates/ Recorded per entry and reconciled against the objects held lib/openagents/forge/sync.ex:161, INVARIANTS.md REPOSITORY-003
Log tamper-evidence None. No chain, no per-entry digest, no signature; content addressing is a naming convention, unverified on read crates/walgit-proto/proto/walgit/v1/wal.proto:141; crates/walgit-wal/src/sync.rs:330 Chained: each entry commits to its predecessor, and entry bytes are re-hashed against the recorded key lib/openagents/forge/wal.ex:269, lib/openagents/forge/verification.ex:18
Published commitment to the log None no anchor, digest, or attestation surface in crates/ Hourly document at /.well-known/openagents-forge-anchor.json, itself chained by previous_digest lib/openagents/forge/anchor.ex:74, lib/openagents_web/router.ex:390
Verification without a database Not applicable; there is no database walgit's GOAL.md §1 Proven: the verifier's compiled import table must not reach Ecto, Postgrex, or OpenAgents.Repo INVARIANTS.md EXIT-002
Events out Bridge tails the log from a durable cursor and posts webhooks, exactly once per repository, sequence, and ref walgit's AGENTS.md D32 PubSub broadcast and a background mirror task, both fired from the push path lib/openagents/forge/pushes.ex:428
Per-repository settings Published as a SETTINGS entry and carried inline on the manifest crates/walgit-proto/proto/walgit/v1/wal.proto:64 PostgreSQL rows in repositories lib/openagents/repositories/repository.ex:20
Durable state outside the bucket None walgit's AGENTS.md principle I PostgreSQL: issues, projects, receipts, memberships, auth docs/taxonomy.md, the layer diagram

3. What walgit has that we do not, and whether we should want it

Each item carries a judgment. Some of these we should want; some are answers to a problem we do not have. The distinction matters more than the list.

3.1 Log checkpoints and compaction — want, and want first

What walgit does. A log checkpoint writes checkpoints/<seq>/refs.pb and checkpoint.pb, then CASes the manifest to advance min_seq and drop every folded log segment (crates/walgit-wal/src/checkpoint.rs:232). Cold start becomes snapshot plus tail. Compaction folds fresh packs geometrically under a lease and publishes the result as a COMPACT entry naming what it supersedes, so replicas download the compacted pack instead of repacking (crates/walgit-server/src/ops.rs:673, crates/walgit-wal/src/publish.rs:1000).

Should we want it. Yes, and ahead of everything else in this section. Section 5.1 states the cost we pay without it.

What it would cost here. More than it looks, because the coupling is in the index format. next_seq/1 is length(entries) (lib/openagents/forge/wal.ex:335), so a folded list changes what a sequence number means. EXIT-002's entry_sequence_broken finding quantifies over the contiguous run from zero, and EXIT-005's chain walks the entry list to recompute links, so both invariants move with the format. A checkpoint would have to carry enough for the chain to remain checkable across the fold, or the chain's start moves and chained_from has to mean "since the checkpoint" rather than "since the contract landed". That is a design question, not a refactor, which is why this document proposes it rather than performing it.

Two things make it cheaper than the full walgit shape. We do not need compaction to make reads cheap, because we do not serve repositories that stress pack lookup; we need it to stop the log from growing. And a first version could fold the index alone — a checkpoint object holding the ref map at a sequence, with the index carrying a pointer and only the tail — without touching packs at all. That alone removes the download-everything and upload-everything costs.

3.2 Git LFS — want, or refuse honestly

What walgit does. A batch API and basic transfer with objects in the bucket, plus optional read-through from an upstream LFS server for imported repositories.

What we do. Nothing. OpenAgents.GitHub.lfs_warning_inputs/3 computes a one-time warning at import (lib/openagents/github.ex:125), and the import screen tells the person that "Git LFS pointer files are copied, but Git LFS objects are not included in this release" (lib/openagents_web/live/repository_import_live.ex:121).

Should we want it. The scale argument does not apply to us, but the correctness argument does: an imported repository that used LFS is broken at the blob level, and the current answer is a warning rather than a refusal. This is a product gap in the import surface, not a git-hosting gap.

What it would cost here. An LFS batch endpoint plus object storage under the WAL prefix is small; WAL.put_object/3 already exists (lib/openagents/forge/wal.ex:59) and the artifact path already stores content-addressed blobs beside the log (lib/openagents/forge/wal.ex:162). The larger question is whether LFS objects are WAL entries — they are not, in walgit, and they should not be here either, because they are not part of the ref record.

3.3 Protocol v2 — we mostly have it, and our moduledoc disagrees with itself

What walgit does. It implements v2 itself: the capability advertisement is hand-written (crates/walgit-server/src/smart.rs:139), and upload_pack_v2 dispatches ls-refs, fetch, object-info, and bundle-uri (crates/walgit-server/src/smart.rs:202). It parses the fetch request — wants, haves, done, filter, deepen, deepen-since, deepen-not, shallow, sideband-all — and then, by default, re-serializes it to a stock git upload-pack --stateless-rpc subprocess to generate the packfile (crates/walgit-git/src/lib.rs:2445). Its own gitoxide engine runs only where stock git cannot: against a base pack read from the bucket.

What we do. lib/openagents/forge/git_http.ex:3 calls the module "Git smart-HTTP v0", and :19 says the Git-Protocol header "is passed through so protocol v2 works". Both the advertisement and the RPC set GIT_PROTOCOL in the stock binary's environment (lib/openagents/forge/git_http.ex:554, and the advertisement at :68), which is how v2 is served over smart HTTP. Read together, the two lines of the moduledoc disagree, and the first one is the one people quote.

Should we want walgit's version. No. We inherit v2 negotiation, ref prefixes, filters, shallow, and sideband-all from the stock binary at no cost. The reason walgit implements the protocol itself is the reason in section 5.4: it wants to answer ls-refs from the log without a materialized repository. Until we want that, implementing v2 buys nothing.

What to do instead. Correct the moduledoc's first line, and settle the behavior with evidence rather than reading — see follow-up 7.6.

3.4 bundle-uri — want later, and not for the reason it exists

What walgit does. Bundles are cut on calendar cron slots as a pure function of the log: for each slot the builder resolves the highest sequence whose created_at is at or before the slot and replays refs to it in memory (crates/walgit-wal/src/log_reader.rs:99), so a bundle built late still contains the state as of its slot and a deleted bundle rebuilds identically. A weekly full carries chained dailies and hourlies above it. Two lists are served: bundles/list with fulls, for clones, and bundles/catchup without them, for fetches — the difference is one filter on an empty base_id (crates/walgit-bundle/src/render.rs:117). A separate blobless family answers --filter=blob:none, because git's bundle-uri client never consults a bundle's declared filter.

Should we want it. Not now, and the honest reason is in walgit's own measurement: for a client that fetches several times a day, upload-pack's thin pack is smaller than an hourly bundle; bundles pay off for fresh clones of a large repository and for far-behind clients. We have neither problem.

What it would cost here. Less than it appears, and more than it appears, in different places. We already produce bundles — the importer creates one (lib/openagents/repositories/importer.ex:328) and the stack ref batch path creates one per batch (lib/openagents/forge/git_plane.ex:553) — so the rendering machinery is partly present. What is missing is the thing that makes bundle slots a pure function of the log: an as-of-sequence ref query, which needs the checkpoint from 3.1 to be affordable. Bundle-uri is downstream of checkpoints, not parallel to them.

3.5 Placement — want when a repository stops fitting, not before

What walgit does. [placement] serve and maintain globs say which repositories a host does object work for. Refs-level reads work everywhere; a host that does not serve a repository answers its object work with 503 and a Retry-After before any synchronization, and names the host that does.

What we do. The opposite, deliberately. Sync.ensure_cluster_fresh/3 warms the repository on every connected node (lib/openagents/forge/sync.ex:43).

Should we want it. Not yet, and the reason is that the two policies answer different questions. Ours is an availability decision: every node can serve every repository, so no request depends on routing. walgit's is a size decision: some repositories cannot fit on some hosts, so placement is the only way to have small hosts at all. The trigger for adopting placement is the first repository that does not fit a node, or a node count at which full replication wastes more than it buys. Neither has happened.

3.6 Leases — want exactly when we get a maintenance unit, plus one case today

What walgit does. A CAS-with-TTL lease at leases/<name>.pb, with holder, purpose, acquired_at, expires_at, and a heartbeat epoch (crates/walgit-store/src/coord.rs:298). It is used for exactly two things: compaction and bundle builds. Publishing takes no lease, because the manifest CAS already serializes it, and log checkpoints take none either, because they are deterministic for a given state — a writer that dies mid-checkpoint leaves garbage, never a hazard.

Should we want it. For the WAL, only when we have a maintenance unit expensive enough that running it twice matters, which means after 3.1. That restraint is worth copying: the lease is not a general coordination primitive in walgit, and adding one before there is work to serialize would invite exactly the second-authority problem EXIT-003 exists to prevent.

There is one case today. mirror_now/1 is a force push of every ref and cannot detect a mirror that is ahead; docs/2026-08-21-repository-storage-architecture-audit.md §3.1 ranks it as the largest blast radius in the system and says in as many words that "the boundary needs a lease, not just a direction". A CAS lease in the WAL bucket is a natural fit and would not make the mirror an authority, because a lease says who may write, not what is true.

3.7 The remote reader — an answer to a problem we do not have

What walgit does. For a repository whose live pack set exceeds an instance's cache budget, only the pack indexes are downloaded; pack data stays in the bucket and is read with 1 MiB range GETs through a process-wide block LRU, with delta chains resolved in process and decoded objects cached (crates/walgit-wal/src/remote.rs:28, :82, :424). The web API faults exactly the objects a git command will touch into the loose store and then runs unmodified git renderers. Protocol v2 fetch works against it; protocol v0 is refused with a message naming the fix, because v0 goes through the stock subprocess and stock git cannot read a pack that is not on disk (crates/walgit-server/src/smart.rs:768).

Should we want it. No. We do not host a repository we cannot materialize. The audit at docs/2026-08-21-repository-storage-architecture-audit.md §3.4 records that our clone and push are bounded by RAM rather than disk, and the fix for that is streaming through the existing put_entry_file/3 and get_entry_file/3 paths (lib/openagents/forge/wal.ex:117, :141), not range reads into pack indexes.

What to take from it anyway. The refusal, not the reader. walgit's check_fits turns a pack set larger than the budget into a 503 with a message that names the alternative, before any bytes move. We have no admission check at all; a repository too large for a node fails somewhere inside a request instead of being refused at the door.

3.8 The events bridge — a rule we already believe and do not yet follow

What walgit does. Decision D32 forbids the push path from producing side effects. A separate bridge tails each repository's log from a durable cursor at events/cursor.json, converts committed entries to ref events, posts them, and advances the cursor only after the webhook acknowledged, so a crash loses nothing and lag is head_seq minus the cursor. Its principle III states the test: "If this side effect fails, does the push?" and "Is it replayable from the cursor?"

What we do. mirror_async/1 starts a supervised task from inside the push path when a mirror URL is configured (lib/openagents/forge/pushes.ex:428). It is best-effort and never blocks or fails the push, which satisfies the first half of walgit's test. It fails the second: a mirror push lost to a restart is not replayable from a cursor, and INVARIANTS.md EXIT-003 records the operational consequence — the mirror is off today, and turning it on force-pushes over whatever direct pushes left there.

Should we want the bridge shape. For the mirror, yes, and it is the same fix as 3.6: a cursor plus a lease turns the mirror from a fire-and-forget side effect into a reader of the log that cannot skip and cannot double-write. Our push receipts already work this way — Pushes.reconcile_receipts/1 re-derives them from the WAL keyed by index position (lib/openagents/forge/pushes.ex:209) — so the pattern is in the codebase and applied to one consumer out of two.

4. What we have that walgit does not

State the asymmetry first. walgit is a git host and nothing else; its GOAL.md scope section exists to keep it that way, and principle X asks of every new dependency, "Which line of GOAL.md §4 is this for?" Our forge is one plane of a product whose issues, projects, receipts, memberships, and authorization live in PostgreSQL. Most of what follows is therefore product rather than git hosting, and comparing it to walgit is comparing a component to a system. Two items are not, and they come first.

4.1 A tamper-evident log

This is the one place where our git-hosting layer does something walgit's does not, and the gap is larger than expected.

walgit has no cryptographic chain over its log. LogEntry has no prev_hash, no digest, and no signature (crates/walgit-proto/proto/walgit/v1/wal.proto:141); the framing is a length prefix and a protobuf body with no checksum. Packs are named by their own trailing SHA, but that name is not verified on any read path: download_object checks size only (crates/walgit-wal/src/sync.rs:330), install_pack renames without index-pack --verify, and the remote reader never re-hashes a decoded object against the oid that was asked for. Content addressing in walgit is a naming convention, checked at client ingest by git index-pack and nowhere else. An operator with bucket write access can rewrite a log segment and CAS the manifest to match, and no replica has anything to notice with. Its docs/INTEGRITY.md does not claim otherwise; it is scoped to accidents — a bad import, an over-eager collection, a compaction that dropped objects — and states no adversary model.

Ours does more, and states its limits with the same care. Every entry carries a link: sha256 over a domain tag, the previous entry's link, and a canonical encoding of the entry's own fields, computed in the one function every writer reaches the log through (lib/openagents/forge/wal.ex:269, :213). Verification.verify/2 recomputes the chain, re-hashes each entry's bytes against the content-addressed key the index recorded, and reports chain_link_mismatch, chain_link_missing, entry_digest_mismatch, entry_sequence_broken, served_refs_diverged, object_missing, and object_unreachable (lib/openagents/forge/verification.ex:13). It reaches no database at all, and EXIT-002 proves that structurally by reading the module's compiled import table.

The limit is stated as plainly as the property, in EXIT-005 and in lib/openagents/forge/wal.ex:29: the chain makes a rewrite total rather than impossible, so an operator who recomputes every link produces a self-consistent log that a verifier with no outside commitment reports clean. While this comparison was being written, a separate lane closed the publication half. OpenAgents.Forge.Anchor writes a document naming each public repository's entry count, head sequence, head chain link, and ref-map digest, chained to the anchor before it by previous_digest, and serves it verbatim at /.well-known/openagents-forge-anchor.json (lib/openagents/forge/anchor.ex:74, lib/openagents_web/router.ex:390, and docs/decisions/0008-publish-the-forge-wal-anchor-at-a-well-known-path.md).

That module's own account of what it proves is the reason this is worth citing in a comparison document: "On its own, nothing. The operator serves the document and could serve any document." Forge.Independence therefore publishes anchor_published and anchor_witnessed as two separate facts and stays degraded on the second, counting anchors actually written rather than reading a configuration flag (lib/openagents/forge/independence.ex:129).

So the honest comparison is: we hold a property walgit has none of, we publish a commitment to it where a stranger can copy it, and we say on the same page that nobody has attested to it yet.

4.2 An invariant ledger with executable proofs

Both projects keep a written contract, and comparing them as artifacts is a genuine like-for-like.

walgit's is in AGENTS.md: ten numbered principles, each with "the tell in a PR" and "the question to answer", plus 32 decisions in force under an append-never-silently-change rule, plus nine invariants restated in README.md. Enforcement is review, a simulation suite with fault injection, and a cost model in docs/ROUNDTRIPS.md that a protocol change has to argue against. Its sharpest instrument is healthy_request_round_trip_budgets, which pins push at 5 requests, warm refs at 1, cold refs at 2, and a checkpoint at 4 (crates/walgit-server/tests/sim.rs:1645).

Ours is INVARIANTS.md: 123 contracts, each with a status and an entry in a proof index, and ops/ci/docs-check.exs fails the gate when a Current contract has no executable proof file, when an ID is duplicated, when the proof index and the sections disagree, or when a contract names a path that does not resolve.

The comparison is not flattering in one direction only. Our ledger is an order of magnitude larger and covers the whole product rather than one component, and it is machine-checked in ways walgit's is not. But ops/ci/docs-check.exs checks that a proof file exists, not that the proof can fail for the claim — and docs/2026-08-23-invariant-proof-audit.md exists because that gap produced four false contracts, ADMIN-001 among them, each green while its claim was false. walgit's budget test is a better artifact than anything we have for the property it covers: it is a number, it is measured, and a regression turns it red. We should want that shape, applied to a property we care about.

4.3 Receipts and the deployment plane

docs/taxonomy.md keeps the planes apart: a push is a receipt, not a deployment, and a push never promotes itself. walgit has no counterpart to either half. Push receipts are derived from the WAL and re-derivable from it (lib/openagents/forge/pushes.ex:209, INVARIANTS.md EXIT-003); build, deploy, and gate receipts record what the deployment plane did; and the plane itself — promotion, build, artifact verification, hot loading, boot convergence, rolling replacement — has no analogue in a git host and should not.

One decision from that plane is worth naming here because it is the sharpest expression of the shared architecture. Commit 6a5cf7d gave forge_builds and forge_deploys a repository_id foreign key and deliberately declined to give one to forge_pushes. The reason is in lib/openagents/forge/receipt_repository.ex:14 and in EXIT-003: forge_pushes.repo is a storage key with a unique index, so it already names one repository, and a key only PostgreSQL could produce would not survive reconcile_receipts/1, which rebuilds the table from the WAL alone. EXIT-003 records the absence as the invariant holding rather than as an omission. That is our version of walgit's "the bucket is the repository", reached from the opposite direction: walgit has no database to be tempted by, and we have one and had to name the temptation.

4.4 Disclosure

Forge.Visibility gives each repository a public level — dark, pulse, ledger, glass — governing what the transparency surfaces may show (lib/openagents/forge/visibility.ex:6), and OpenAgents.Transparency applies the same four tiers to artifacts. Forge.Independence publishes, on the status page, a derived answer to three questions about what the operator can do, with degraded as their disjunction and every claim counted from a ledger rather than restated by hand (lib/openagents/forge/independence.ex:2, INVARIANTS.md EXIT-006).

walgit's bundled web UI carries a health page for the WAL, which its README.md lists beside the tree, blob, commit, and diff views. It has no notion of disclosing what its operator can do, and for a self-hosted single-tenant binary that is a reasonable scope: the operator is the reader.

4.5 Everything above the git plane

Issues, projects, milestones, labels, the GitHub-shaped /api/v3 subset, evidence chains, accepted outcomes and completion claims, the forum, memberships and API-token scopes. None of this is a comparison; it is the reason the two repositories are different sizes. walgit is 68,231 lines that host git. lib/openagents/forge/ is 15,519 lines that host git and drive deployments, inside an application that does much more.

5. Where walgit's design exposes a weakness in ours

This is the section worth the document. Each item is a property walgit has that we lack, stated as the cost we are paying rather than as a feature we are missing.

5.1 The index is the log, so every read and every push carries the whole history

We have no log checkpoint and no compaction. A search of lib/openagents/forge/ for checkpoint, compact, snapshot, and repack returns nothing in the WAL, its adapters, or the synchronizer; the only hits are unrelated — BuildArtifact's BEAM compact-integer decoder, DeploymentNode's prior-state snapshot, and the thread save point docs/taxonomy.md records as proposed. The absence is structural rather than accidental: the index document carries "entries", the full ordered list of every entry ever appended with each entry's complete post-state ref map (lib/openagents/forge/wal.ex:12), and next_seq/1 is length(entries) (lib/openagents/forge/wal.ex:335). Nothing can fold that list without changing what a sequence number means.

Four costs follow, and they compound.

  • Every read downloads the whole index. read_index/1 issues an unconditional metadata GET for the generation and then an unconditional media GET for the body (lib/openagents/forge/wal/gcs.ex:37, lib/openagents/forge/wal/gcs.ex:251). There is no conditional GET, no ETag, no 304, and no freshness window.
  • Every push uploads the whole index. cas_index/3 re-encodes and re-uploads the entire document under ifGenerationMatch (lib/openagents/forge/wal/gcs.ex:46). Push cost is linear in total push count.
  • A cold node replays every entry. do_replay_missing/3 walks the entry list and runs one git receive-pack per unapplied entry, each preceded by a download of that entry's payload (lib/openagents/forge/sync.ex:108, lib/openagents/forge/sync.ex:232, lib/openagents/forge/sync.ex:336). There is no snapshot to start from.
  • The bucket keeps every push pack forever. Entries are immutable and content-addressed, and nothing supersedes them.

walgit's manifest is the opposite shape and the proto comments say why. Manifest carries head_seq, min_seq, a CheckpointRef, a list of LogSegmentRef pointers, the live PackRef set, and inline settings — no entries (crates/walgit-proto/proto/walgit/v1/wal.proto:27). Log checkpoints fold the list: checkpoint.rs writes checkpoints/<seq>/refs.pb and checkpoint.pb, then CASes the manifest to advance min_seq and drop every folded log_segments entry (crates/walgit-wal/src/checkpoint.rs:232). Folding fires on any of three triggers — 256 entries, an 8 MiB log tail, or an hour — and it is refs-level work, so an instance that could never hold the repository's packs can still write one (crates/walgit-wal/src/checkpoint.rs:38, crates/walgit-wal/src/checkpoint.rs:91). Geometric compaction is published as a COMPACT entry naming the packs it supersedes, so a replica downloads the compacted pack and drops the sources instead of repacking (crates/walgit-wal/src/publish.rs:1000, crates/walgit-wal/src/sync.rs:946).

This is not a new finding. docs/2026-08-21-repository-storage-architecture-audit.md §3.9 already records it as "The WAL index grows without bound and is rewritten on every push", ranked low now and certain later, and adds a multiplier this comparison did not have to find: Forge.Janitor reads the index of up to 1,000 ready repositories every hour on every node, which is still true today (lib/openagents/forge/janitor.ex:29, :54, :122). What walgit adds is the demonstration that the fix is neither large nor exotic, and a worked example of the exact shape it takes.

5.2 There is no round-trip budget, and nothing would notice a regression

walgit treats bucket round trips as the performance design rather than as an implementation detail. Its docs/ROUNDTRIPS.md states the primitive costs it measured (60–80 ms for a small GET or PUT, 15–18 ms for a conditional GET that answers 304, a free 404, roughly one serialized write per second on a CAS'd object), tabulates the budget every operation must defend, and requires a protocol change to argue against that table. Its AGENTS.md principle VII makes "count the round trips" a review question, and healthy_request_round_trip_budgets pins the numbers in a simulation test: a healthy push at 5 requests, a warm refs read at 1, a cold refs sync at 2, a log checkpoint at 4 (crates/walgit-server/tests/sim.rs:1645).

We have no equivalent artifact. Our warm refs read costs two unconditional requests plus the full index body, and no test asserts a number, so a change that made it four would land silently. This is a gap in the invariant ledger's coverage as much as in the code: INVARIANTS.md binds correctness properties of the WAL thoroughly and cost properties not at all.

5.3 Reads serialize on a per-repository lock held across the network

Every read path calls Sync.ensure_fresh/2, which runs inside with_repo_lock/2 — a :global.trans on {{OpenAgents.Forge.Sync, repo}, self()} over [node()] (lib/openagents/forge/sync.ex:83, lib/openagents/forge/sync.ex:101). Two unconditional GCS requests happen inside that lock, and so does any replay. Concurrent clones of one repository on one node therefore serialize behind each other's bucket latency, and a cold cache serializes them behind a full replay.

walgit's decision D19 exists because it hit exactly this: "one 24-minute clone once starved every info/refs for minutes". Its answer is to split the phases — the refs phase takes only sync_mutex, pack materialization runs on a separate bulk runtime, pack removal uses try_write() so a queued writer never blocks new readers, and control-plane objects never share a transport or a permit with bulk bytes.

5.4 Serving refs requires the whole repository on disk

advertise/4 synchronizes the cache and then runs git upload-pack --advertise-refs against the local bare repository (lib/openagents/forge/git_http.ex:63, lib/openagents/forge/git_http.ex:68). A ref advertisement therefore needs every object the repository holds to be present locally, even though the WAL index already carries the exact ref map the advertisement would print (lib/openagents/forge/wal.ex:341).

walgit's Refs sync level answers info/refs, ls-refs, bundle lists, and its web refs endpoints from the log checkpoint's ref snapshot plus the log tail, writing refs offline with no git update-ref "so it works before the packs exist locally" (crates/walgit-wal/src/sync.rs:929). That is what lets it serve a repository larger than the instance at all, and it is also why its cold path is two requests rather than a replay.

We do not host a repository we cannot materialize, so this is not a live incident. It is a ceiling: the first repository that does not fit a node is a repository this forge cannot serve in any degraded mode, and today nothing refuses it early either — there is no counterpart to walgit's check_fits, which turns a pack set larger than the cache budget into a 503 before any work starts.

5.5 The ordinary push path enforces no ref policy

repositories.protected_branches exists as a column (lib/openagents/repositories/repository.ex:20), and authorize_receive_pack/3 consults it — but only for an :assignment principal (lib/openagents/forge/git_http.ex:284, lib/openagents/forge/git_http.ex:304). Every other principal that passed the write authorization falls through the last clause to :ok (lib/openagents/forge/git_http.ex:299). An ordinary token with forge:write may force-push or delete any ref, including the default branch, and the protected-branch list does not apply to it.

walgit's decision D16 makes push authorization a per-repository rule language published at policy.json, with an envelope of version, groups, and rules, where protect is a conjunction, and a missing file means "anyone with write may move any ref" — the same default we have, but reached deliberately and with a mechanism to change it per repository.

This is the smallest item here and probably the easiest to close, and the gap between the column's name and its actual reach is exactly the kind of claim docs/2026-08-23-invariant-proof-audit.md was written about.

5.6 Nothing folds or audits the log, and nothing checks what the projection holds

We have three scheduled jobs beside the git plane and none of them looks at the repository. Forge.Janitor sweeps stale per-job clones and build artifacts and re-derives push receipts, and its moduledoc is explicit that it "Never touches bare repos or the WAL: those are re-materializable truth, not cache to expire" (lib/openagents/forge/janitor.ex:15). Forge.MirrorWatch exports accepted commits. Forge.AnchorPublisher reads each public repository's log head hourly and publishes a commitment to it (lib/openagents/forge/anchor_publisher.ex:28). Reading the head is not auditing the log, and none of the three would notice a projection that cannot be walked.

walgit's maintainer is a different kind of object. Its output is a pure function of (config, WAL), it computes the desired state every pass and performs one bounded unit of the most important missing work, in a fixed priority order: log checkpoint, then repair, then missing bundle slots oldest first, then compaction, then reverse-index backfill, then a connectivity audit whose report is written to fsck.pb and consumed by the repair unit (crates/walgit-server/src/maintain.rs:271, crates/walgit-server/src/maintain.rs:398). An outage leaves no permanent hole, because a missing artifact is one that has not been built yet and the next pass builds it.

The consequence for us is section 6.

6. What walgit's design would have done about #179

On 2026-08-23 the live forge was found unable to serve a full clone of its own repository. The cause is recorded in commit f29fb0d and in the amendment to REPOSITORY-003: this repository's log was seeded from a --depth=1 fetch, which copies one commit per ref and no ancestry, and it was written before WAL entries carried a shallow key. The log recorded no boundary, replay had none to write, and the projection reached disk holding a commit whose parent it did not have. Every check the forge had asked whether ref tips resolved, and they all did, so EXIT-004 stayed green while a clone aborted on c91327d6.

Asking what walgit would have done gives four separate answers, and one of them is uncomfortable.

Its push path would not have prevented it. walgit's receive-pack connectivity check runs with stop_at_existing_refs = true, which hides everything already reachable from current refs from the walk (crates/walgit-server/src/smart.rs:1191, crates/walgit-git/src/lib.rs:1487). That is the same assumption ours makes and the same reason a shallow seed passes: the check asks whether the new objects connect to what is already there, not whether what is already there connects to anything.

Its import path would have caught it, with the command our fix now uses. walgit import --direct runs verify_refs_in_packs, which builds a scratch bare repository over the pack directory and runs git rev-list --objects --missing=print (crates/walgit-cli/src/import_direct.rs:983, called at :458). That scratch repository has no shallow file, so a shallow-seeded pack reports its absent parents as missing and the import fails closed. Our fix reaches the same place by the same route: Sync.servable?/1 runs git rev-list --objects --quiet --all and derived_boundaries/1 runs git rev-list --all --parents --missing=print (lib/openagents/forge/sync.ex:192, :199). The convergence is worth noticing — the traversal that would fail a clone is the only honest population for the check — but so is the timing. walgit runs it at seed time and refuses; we ran nothing at seed time and added the traversal after a person could not clone.

Its maintainer would have found it within seven days. The connectivity audit runs git fsck --connectivity-only on a cadence of maintenance.fsck_interval, default seven days, writes a FsckReport to fsck.pb, and sets a walgit_repo_missing_objects gauge per repository (crates/walgit-server/src/ops.rs:217, :277, crates/walgit-server/src/maintain.rs:398). walgit writes no shallow file and has no concept of a graft — a grep for graft over its crates returns nothing — so a shallow-seeded repository is, to walgit, a repository with missing objects, which is exactly what the audit reports. We had no scheduled audit of the object graph, and still do not, and that is the real difference: not that walgit is cleverer about shallow state, but that it looks.

Two caveats keep this honest. The audit is the lowest-priority unit and only runs when nothing else is due, and it is gated on the whole pack set fitting locally (crates/walgit-server/src/maintain.rs:400), so a repository served from the bucket is never audited on that host.

Its repair is unavailable to us by invariant, and that is the uncomfortable part. When the audit finds missing objects, walgit promotes a repair unit only if upstream.git is configured (crates/walgit-server/src/maintain.rs:286). Repair fetches the missing object IDs from that upstream with --depth=1, packs exactly those IDs, and publishes them as a tier-0 entry (crates/walgit-git/src/repair.rs:74); with no upstream, the gap sits in the gauge and nothing heals. So walgit's answer to a hole in history is fetch it from somewhere else.

For us, "somewhere else" is GitHub, and EXIT-003 forbids it. The proof reads the compiled import tables of Forge.Sync and Forge.Repos and fails on a call into Forge.MirrorWatch or into the mirror functions of Forge.Pushes, precisely so a lost forge cannot quietly promote the mirror to source of truth through a fallback someone added during an incident. walgit can heal history because it never claimed the bucket was the only authority for object bytes; we claimed it, we hold it, and the price is that a hole the WAL never held stays a hole.

That is the right trade and it should stay. But it changes what our answer to #179 has to be. walgit's answer is repair; ours can only be record the boundary honestly and detect the hole early, which is what f29fb0d does — a derived graft so a clone succeeds and reports that history ends there, plus object_unreachable so the traversal that would fail a clone is the population under test. What is still missing is the third leg walgit has and we do not: something that runs the traversal on a schedule rather than on demand, so the next hole is found by the forge instead of by a person cloning.

7. Follow-ups

Each is specific enough to become an issue. None is a decision; the doc is a comparison, and INVARIANTS.md is not edited here.

  1. Fold the WAL index behind a checkpoint object. Move the entry list out of the index and leave a head sequence, a checkpoint pointer, and a tail. Settle first what a fold does to EXIT-002's entry_sequence_broken, to EXIT-005's chain and its chained_from, and to next_seq/1's definition as length(entries) (lib/openagents/forge/wal.ex:335). This is the largest item here and the prerequisite for several others. It closes docs/2026-08-21-repository-storage-architecture-audit.md §3.9.

  2. Make the index read conditional. read_index/1 issues two unconditional requests and downloads the whole body every time (lib/openagents/forge/wal/gcs.ex:37, :251). An If-None-Match against the stored generation, with a bounded freshness window, would make the common case one cheap request. Pair it with a test that asserts the request count, in the shape of crates/walgit-server/tests/sim.rs:1645.

  3. Bind the ordinary push path to protected_branches. authorize_receive_pack/3 consults the column only for an :assignment principal (lib/openagents/forge/git_http.ex:284); every other write principal falls through to :ok at :299. Decide whether the column means what its name says for every principal, and make the proof quantify over principals rather than over the assignment surface — the failure mode docs/2026-08-23-invariant-proof-audit.md names.

  4. Run the connectivity traversal on a schedule. Verification.verify/2 already computes object_unreachable from rev-list --objects over the exportable refs (lib/openagents/forge/verification.ex:313). Nothing runs it unattended. A periodic pass that records the result and surfaces a non-empty finding would have found #179 without a person cloning. Forge.AnchorPublisher is the nearest precedent for the shape — a scheduled reader of the WAL that is not on the push path and cannot fail one (lib/openagents/forge/anchor_publisher.ex:2) — and a companion job could reuse it. Decide where the result lives, given that it must not become a second authority.

  5. Give the mirror a lease and a cursor. mirror_async/1 fires from the push path and is not replayable (lib/openagents/forge/pushes.ex:428), and mirror_now/1 force-pushes every ref with no way to detect a mirror that is ahead — the largest blast radius in docs/2026-08-21-repository-storage-architecture-audit.md §3.1. A durable cursor plus a CAS lease in the WAL bucket makes the mirror a reader of the log, the shape walgit's decision D32 requires of every side effect.

  6. Settle which protocol versions the forge actually serves, with evidence. lib/openagents/forge/git_http.ex:3 says v0 and :19 says v2 works; both cannot be the headline. A GIT_TRACE_PACKET clone against staging that asserts the negotiated version would settle it, after which the moduledoc says one thing.

  7. Refuse a repository that cannot be materialized, at the door. There is no counterpart to walgit's check_fits, so a repository too large for a node fails inside a request. A bounded admission check that answers 503 with a message naming the limit is small and independent of everything else here.

  8. Decide what the import surface promises about Git LFS. Today it copies pointer files and warns (lib/openagents_web/live/repository_import_live.ex:121). Either implement the batch API with objects under the WAL prefix, or make the import refuse a repository that uses LFS. The warning is the one option that leaves a person with a repository that looks imported and is not.

8. What this document could not settle

  • Whether protocol v2 is negotiated end to end in production. The delegation is unambiguous in the source — GIT_PROTOCOL reaches the stock binary on both the advertisement and the RPC — but no test or trace in this repository asserts the negotiated version. A GIT_TRACE_PACKET clone against the live forge would settle it. Follow-up 7.6.
  • The live size of this repository's WAL index and its entry count. Both determine how urgent follow-up 7.1 is, and neither is readable from the repository. Reading the index object from the bucket would settle it.
  • walgit's behavior under load. Everything here is read from its source and its simulation tests. Its AGENTS.md records measurements taken during its own development, and the throughput figures in the Cursor post belong to Continuity rather than to walgit. Nothing in this comparison was measured by running either system.
  • Whether walgit's stated invariants hold in practice. Two research passes over its crates found six places where its own documentation overstates the code — including a format_version the proto says readers reject and no reader checks, ENTRY_KIND_CHECKPOINT entries that nothing writes, log-segment merging that does not exist, and a compaction.retention_superseded knob with no reader, meaning superseded packs accumulate in the bucket indefinitely. Those are findings about walgit's documentation, not about its correctness, and this document reports them without having run it.