Forge: how it works

A forge is trusted for three things git does not do by itself: saying which object a branch points at, saying who may move it, and recording that a human reviewed the move. Those three are what lives here. The objects do not: they stay in git, behind whatever mirror the repo declares.

The reference log

Every ref move is one entry in an append-only, hash-chained log. An entry names the ref, the object it left, the object it reached, the actor, the block and the kind: create, update, force, delete or merge: and commits to the digest of the entry before it. Pin the head digest anywhere off chain and the entire history becomes falsifiable.

Moves are compare-and-swap: the caller states the tip it expected, and a stale expectation aborts instead of overwriting. That is git's --force-with-lease, except the lease is held by consensus rather than by the server you push to. A move that skips the discipline is not forbidden, it is recorded as a force.

The chain has no objects, so it cannot check that a new tip descends from the old one. It does not pretend to. Ordering, attribution and policy are on chain; ancestry is verified by a client that has the repo.

Namespaces

A repo id is "namespace/name". A namespace is either a name you hold in r/sys/users or your own address, so "g1.../forge" works with nothing registered and "moul/forge" needs the name. Nobody can claim a namespace they do not own, and a realm passes the same test a user does, by its address.

Roles

reader < writer < maintainer < admin < owner. Writers move refs, maintainers force and merge, admins manage members and policy. A role can be held by another realm, so a repo owned by a DAO is a repo whose merge button is a vote.

Reviews

Anyone may open an issue or a change request, and anyone may review one: the spam gate is that you pay for your own bytes. Only a writer's approval counts toward the merge policy, and an approval names the object it reviewed: push a new head and it stops counting, with nothing to remember to dismiss.

Calling it

gnokey maketx call -pkgpath gno.land/r/moul/forge/v0 \
  -func SetRef -send "" -gas-fee 1000000ugnot -gas-wanted 3000000 \
  -args "moul/forge" -args "refs/heads/main" \
  -args "<expected-oid>" -args "<new-oid>" -args "ship it" \
  -broadcast -chainid <chain> -remote <rpc> <key>

Read paths are free: vm/qeval on RefOID, LogHead or HasRepo, or just browse the routes above.