Module notes

Expand description

The notes refs as origin’s mirror (SPEC.md, “Which refs are read”).

Structs§

Publish: How a publish is carried out. Every producer and every signed-notes ref (attestations, their inputs, provenance) goes through the same loop.
Synced: What one name set’s sync came to: the state of its notes ref and of its inputs ref, and the lines that report a change to the repository’s refs (a mirror deleted, with how to restore it).

Mirror: What became of one notes ref. SPEC.md, “Lookup”.
Published: What a publish came to.
PushFailure: Why a push that exited non-zero failed, read from git’s stderr.

classify_push: The markers behind PushFailure. Raced wins over Unreachable: a message naming both is a race that happened on a reachable remote. A hook’s own output rides the same stream, so Unreachable is read only from the lines git and ssh themselves print.
publish: Attach each (object, block) on the REMOTE’s copy of notes_ref (short name, under refs/notes/) and push. Never notes add -f, which erases every other producer’s block, and never a push of the local ref, which would re-publish a block origin revoked:
publish_local: The same, into the local notes_ref only, with no remote involved: what sign --no-push writes under refs/notes/attest-local/.
sync_mirrors: Bring both mirrors of the written names (WRITE) in line with origin: one fetch of both refs into throwaways and, when that fails without timing out, one ls-remote to tell “origin has no such ref” from “origin did not answer” — then, if some refs exist, one more fetch of those. A silent origin costs one call (15 s at most), a dead one two (30 s), the worst case three (45 s).
sync_mirrors_of: sync_mirrors for one name set’s two refs. A verifier syncs each set on its own, so a set origin does not have (the old one after the census, the new one before the writers switch) is Deleted, which judges nothing and changes no verdict, never Unreachable.