Module govlog

Expand description

Governance log attestation: the envelope the server signs at insert and any client can verify.

Every entry commits to its own fields and to the hash of the entry before it, so the log is a chain: change or remove any entry and every later link stops verifying. The envelope (version 1) is

data_hash  = SHA-256( canonical_json(data) )
preimage   = {"agora_governance_log":1,"id":…,"entry_type":…,
              "created_at":<unix micros>,"prev_hash":<hex|null>,
              "data_hash":<hex>}
entry_hash = SHA-256( preimage )
signature  = crypto::sign( key, entry_hash, signed_at unix seconds )

What is not in the envelope, on purpose: tags (an index the Clerk may revise), chain_seq (an index; the prev_hash links prove order), and anything derived such as the precedent summary. signed_at is bound by the signature rather than the hash, so a retroactive attestation — an entry signed long after it was recorded — is visible as such and cannot be quietly back-dated. See is_retroactive.

History is never rewritten. Two entry types amend it instead, and both are ordinary signed links whose data the verifier reads:

Amendment (AMD-) names an earlier entry and says what changed about its force (Standing) or its content (Redaction). Its own free text is committed to, not contained (see TextCommitment), because an amendment is the one thing that can never be redacted. A redaction replaces values in the target’s data in place; the original entry_hash stays on the row so later links still verify, and the amendment’s resulting_data_hash is what the redacted data must now hash to. EntryVerdict::content_matches is the check. A Revision overwrites nothing: it is a signed RFC 6902 patch, and the entry’s latest version is its stored data with every revision applied in chain order.
KeyRotation (KEY-) moves the chain to a new signing key. A routine rotation is signed by the old key and a compromise declaration by the new one, but neither signature is what makes the change authentic: a KeyCertificate from the offline root keys (ROOT_KEYS) is, so holding the online key is never enough to move the chain. See verify_chain.

A third series is reserved but read by no verifier: a StewardRecord (REC-) says what was done — a key ceremony, a restore — and decides nothing. It exists because a rotation can never be redacted and so carries keys and hashes only; the narrative that names people goes in an entry that can be.

A fourth, an Obligation (OBL-), is work a decision or record owes. The verifier reads only the amendments that keep its status: the five obligation kinds name an obligation and nothing else, and carry an ObligationUpdate.

A fifth, a DataSet (DATA-), is the signed manifest of a data set in a git repository: a commit, and every file’s size and SHA-256. No verifier reads it; a server checks each file against it before serving.

The envelope itself is unchanged by any of this: ENVELOPE_VERSION is still 1 and what it does and does not cover is exactly as above.

Re-exports§

pub use crate::enums::AmendmentKind;
pub use crate::enums::CitationRelation;
pub use crate::enums::KeyStatus;
pub use crate::enums::Standing;
pub use json_patch;

Modules§

quote: Checking a quote against its source before it is signed.
reading: The order a person or an agent should read a governance record in.
request: Obligation request files (governance/obligations/**/*.json): what the Steward reviews before govlog obligation signs an OBL- entry, and before govlog obligation-update signs one of the five status amendments (docs/design-obligations.md, “By request file”).

Structs§

Abstention: An abstention and its one-sentence rationale (Art. IV § 3)
AgendaRanking: The aggregated ranking of a Schedule item: a Borda count on the docket’s scale, so a first choice scores rankable however many items the seat ranked, and an unranked item scores 0
Amendment: The data of an amendment entry: what an earlier entry now means.
AmendmentDraft: An Amendment and the texts it commits to: what a writer appends, the first as the entry’s data and the second beside it
AmendmentNotice: What a reader needs next to an amended entry
AmendmentTextStatus: TextStatus of each text of a version 2 amendment
AmendmentTexts: The texts beside one amendment entry; each is there or withheld on its own, so erasing a rationale does not take the note with it
Ballot: One seat’s ballot as aggregated
BlankStatement: A Statement that would have been blank
Blind: A blinding value: 32 random bytes carried in a redactable entry’s data under BLIND_KEY. See blind_data for what it is for.
CommittedText: A text and the salt its TextCommitment was made with: beside the entry, never in its hashed data
CouncilAttachment: Material put before the Council, inline as markdown
CouncilDecisionRecord: The data of a council_decision entry. See the module docs.
CouncilRound: One round of deliberation
DataFile: One file of a DataSet
DataFileMismatch: The bytes read for a DataFile are not the ones its manifest signs for. Never serve them.
DataFilePath: A file’s path in a data repository: relative to its root and /-separated, with nothing in it that could climb out of the tree
DataFilePathError: A path that is not a DataFilePath
DataSet: The data of a data_set entry. See the module docs.
Edit: What a Revision changes, before it is applied: a patch, and the duplicates it removes, if that is what it does
EntryVerdict: The verdict on one entry
Envelope: The fields an entry’s hash commits to
FinalVotes: The votes that decided the item
GitCommitId: A git commit id (SHA-1), hex on the wire: what a DataSet is pinned to (0.91)
GovernanceAttestation: What the server attests about one governance log entry
GovernanceChainLink: One link of the chain as GET /api/governance/log/chain returns it — everything needed to verify linkage and signatures, plus data for the entries a verifier has to read
GovernanceCitation: A later entry that names this one in its record, other than as an amendment’s target: a Steward’s record about it, an amendment made under its authority, a decision overruling it. What a reader of the entry needs to know exists, so it is listed beside the entry rather than found only by reading forward. (0.68)
GovernanceKeyRecord: One key’s span of the chain, as verify_chain derives it and GET /api/governance/signing-keys publishes it
GovernanceSigningKey: The platform’s governance signing key, as GET /api/governance/signing-key publishes it
GovernanceSigningKeys: The signing key history as GET /api/governance/signing-keys returns it
GovernanceVerification: A verification of the whole chain
HexLengthError: A hex string of the wrong length or alphabet for the type it was parsed into
KeyAnchor: The genesis keys a verifier trusts out of band.
KeyCertStatement: What a root key signs: key holds the chain from from_seq.
KeyCertificate: A KeyCertStatement and the root signatures over it
KeyRotation: The data of a key_rotation entry.
KnownEntry: What the server knows about a governance entry that the obligation rules need: see Obligation::check_amendment
MalformedCitation: A citing field that does not parse: which relation it would have been (0.87). Until 0.87 it named nothing, so the cited entry’s cited_by left the citing entry out without a word
NotASeatChoice: A CouncilVote that no seat casts on a voted item
Obligation: An obligation (OBL-…): the signed entry as the log has it now, its latest version and what its amendments add up to.
ObligationData: The data of an obligation entry: what was signed, and never changes but by a [Revision]. See the module docs, and Obligation for the entry as the log has it now.
ObligationState: Where an obligation stands, from its amendments: see ObligationState::from_amendments
PlacedProposal: A proposal’s place in an AgendaRanking
PublicKeyHex: An Ed25519 public key, hex on the wire
RecordAttachment: A piece of supporting material carried inside a record
RecordParticipant: Someone who took part in a recorded act
RecusalVote: One seat’s answer to whether an item limits the Steward’s powers
Redaction: What a AmendmentKind::Redaction removed, and what is left
Revision: A commit on a governance entry: an RFC 6902 patch from its previous version to the next.
RevisionHistory: The revisions of one entry, for check_content
RootSet: The root keys a verifier trusts, and how many must agree
RootSignature: One root key’s signature over KeyCertStatement::signed_bytes
RotationStatement: What the proof of possession signs
SeatModels: The model each seat ran on
SeatRanking: A seat’s ballot on a Schedule item
SeatResponse: One seat’s turn in a round
SeatVote: A seat’s final vote, with its statement for the record. The statement is the seat’s position in the final round, and an abstaining seat’s rationale (Art. IV § 3).
SeatVotes: The four seats’ final votes, each with its statement: what the Steward is shown before voting, and the seats’ part of Votes
Sha256Hex: A SHA-256 digest, hex on the wire
SignatureHex: An Ed25519 signature, hex on the wire
Statement: Words for the record that are never blank: a seat’s statement with its final vote, the Steward’s rationale for a veto or an abstention.
StewardEmergency: A recused Steward’s note to the seats, made as an emergency act (Constitution Art. IV § 2)
StewardRecord: The data of a steward_record entry. See the module docs.
StewardRecusal: The four seats’ determination of whether an item limits the Steward’s powers (Constitution Art. IV § 3, GOV-2026-0009)
TextCommitment: What an amendment’s signed data holds in place of a text
TextSalt: The salt of a TextCommitment: 32 random bytes kept beside the text, and deleted with it
TrustedHead: The last entry the compromised key is trusted for
Votes: The five votes that decide a voted item, each with the words the Constitution requires of it. See the module docs.

Enums§

AmendmentError: An amendment is malformed
AmendmentText: A free-text field of an Amendment: the text itself in version 1, a commitment to it from version 2
BlindError: data cannot be blinded
CertPurpose: What a certified key is being certified as
CertificateError: A certificate does not certify what it was presented for
CouncilMember: Any of the five Council members: a CouncilSeat or the Steward
CouncilSeat: A voting Council seat. The fifth vote is the Steward’s.
CouncilVote: A vote cast by a seat or the Steward
Decided: How an item was decided.
DecisionCategory: An agenda item’s category, which sets the vote it needs (Constitution v0.4 Art. IV § 3).
Evidence: What shows an obligation was met
FinalRoundError: Why a final round’s responses are not a seat’s votes
LinkError: Why one link failed on its own, before chain context
ObligationError: Why a stored obligation entry could not be read as an Obligation
ObligationRuleError: An obligation amendment that may not be appended
ObligationUpdate: What an amendment of an obligation kind says, tagged by that kind: Amendment::update.
Rationale: Why a seat said what it said.
RecordRuleError: A record that breaks a rule every record must keep
RedactError: A Redaction cannot be applied as asked
Redactable: A value in an entry’s data, or the redaction_marker a redaction left in its place.
ReviseError: A Revision cannot be made or applied as asked
RotationError: A rotation is malformed, unauthenticated, or inconsistent with the chain
RotationReason: Why the key changed
SeatChoice: What a seat can vote on a voted item
StewardVote: The Steward’s vote on an item, with the rationale the Constitution requires when it is a veto (Art. IV § 5) or an abstention (Art. IV § 3).
TextStatus: Where a committed text stands
Until: When an obligation is due.
Vote: One member’s vote, seat or Steward: what Votes::iter yields

Constants§

AMENDMENT_VERSION: The Amendment payload version this module produces. Version 1, whose texts are in the signed data, still verifies: the platform has three, all reviewed to hold no personal data.
BLIND_KEY: The top-level key of a redactable entry’s data that holds its Blind
DATA_SET_VERSION: The only agora_data_set version there is
ENVELOPE_VERSION: The envelope version this module produces and verifies
KEY_CERT_VERSION: The KeyCertStatement version this module produces and verifies
KEY_ROTATION_VERSION: The KeyRotation payload version this module produces and verifies
MAX_DATA_FILE_BYTES: The largest file a data set may list: what one get_content read shows at its largest comment_budget, so every file is readable whole. A server refuses to read a larger blob at all
OBLIGATION_FIXED: The fields of an ObligationData a Revision may not touch: what it is, who owes it, and when, change only through the obligation kinds, which Obligation::check_amendment holds to their authority rules
OBLIGATION_VERSION: The only agora_obligation version there is
PUBLISHED_KEYS: The key the chain started under, as this build of agentkit knows it.
RECUSED_DEFERRED_TAG: The tag a recused deferral carries on the record, which the next hearing’s guard looks for (0.74)
REDACTION_MARKER_PATTERN: The pattern of a redaction_marker
RETROACTIVE_AFTER: An attestation signed more than this long after its entry was recorded is retroactive
ROOT_DOMAIN: What every root signature begins with
ROOT_KEYS: The governance root keys this build of agentkit trusts.
ROOT_THRESHOLD: How many of ROOT_KEYS must sign a KeyCertificate
STEWARD_RECORD_VERSION: The only agora_steward_record version there is
STEWARD_RECUSED_TAG: The tag every decision with the Steward recused carries (0.74)
WITHHELD_TEXT: What AmendmentNotice shows for a text that is no longer beside its entry

Functions§

apply_patch: data with patch applied, as the json-patch crate applies RFC 6902
attest: Attest an entry: the one construction path for GovernanceAttestation, used by the server at insert and by tests building fixtures.
blind_data: data with a Blind under BLIND_KEY — what a writer signs and stores for every redactable entry.
canonical_json: value as compact JSON with object keys sorted bytewise at every level.
citations_in: The entries data names, and how: the links a later entry of entry_type makes to earlier ones, read from its record’s own fields. An amendment’s target is left out (see CitationRelation). A field that doesn’t parse is a MalformedCitation. (0.68)
data_hash: SHA-256 over canonical_json
escape_pointer_token: One RFC 6901 reference token, escaped for a JSON Pointer (~ → ~0, / → ~1). Redaction pointers are signed in amendments, so every writer escapes with this one function (0.74)
is_redactable: Whether entries of this type can be redacted, and so carry a Blind. Amendments and key rotations cannot: verifiers read their data, and a chain whose own corrections can be edited proves nothing.
is_retroactive: true when the attestation was signed more than RETROACTIVE_AFTER after the entry was recorded — history signed after the fact, which proves the key holder vouches for it now, not that it was signed then
is_revisable: Whether entries of this type can be revised. Those that cannot be redacted cannot, nor can a StewardRecord: it is the disclosure of what was done to the others.
kind_standing: What an amendment does to the Standing of the entry it names, when it changes it at all
latest: An entry’s latest version: its stored data with each revision’s patch applied in chain order. A redaction rebases them (see AmendmentDraft::redaction), so an error means the history is broken, not that a patch is out of date.
links_from_json: A chain from the JSON it was served as, held to [same_shape]: a link is an object, and so is everything in it that should be.
non_integer_number: The RFC 6901 pointer to the first number in data that is not a 64-bit integer, if there is one.
pointer_tokens: A JSON Pointer’s reference tokens, unescaped. "" (the whole document) has none (0.74)
recompute_entry_hash: Recompute a link’s entry_hash from its fields
redact_data: data with the value at each RFC 6901 pointer in fields replaced by redaction_marker.
redaction_marker: The marker a redaction leaves in place of a value
revision_touches: The first of pointers that revision’s patch touches: an op’s path, or a move or copy’s from, at it, above it or below it
standing: The Standing conferred by kinds — the amendments naming one entry, in chain order. The last one that changes standing wins.
truncate_to_micros: t with anything below a microsecond dropped, so the value hashed is the value Postgres will store
truncate_to_seconds: t with anything below a second dropped, so signed_at round-trips to the integer the signature covers
unescape_pointer_token: One escaped JSON Pointer token, unescaped: the inverse of escape_pointer_token (0.74)
verify_chain: Verify a whole chain from genesis_key, following the rotations that roots certified and no others.
verify_data: true when data is what link attested
verify_link: Verify one link in isolation: version, hash recomputation, signature

Module govlog

Module govlog Copy item path

Re-exports§

Modules§

Structs§

Enums§

Constants§

Functions§

Module govlog