Module govlog 

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.

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::KeyStatus;

pub use crate::enums::Standing;

pub use json_patch;

Modules

reading

The order a person or an agent should read a governance record in.

Structs

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

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

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

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

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.

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

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

SeatRanking

A seat’s ballot on a Schedule item

SeatResponse

One seat’s turn in a round

Sha256Hex

A SHA-256 digest, hex on the wire

SignatureHex

An Ed25519 signature, hex on the wire

StewardRecord

The data of a steward_record entry. See the module docs.

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

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

CouncilSeat

A voting Council seat. The fifth vote is the Steward’s.

CouncilVote

A vote cast by a seat or the Steward

DecisionCategory

An agenda item’s category, which sets the vote it needs (Constitution Art. IV). A Steward veto rejects any of them.

LinkError

Why one link failed on its own, before chain context

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

TextStatus

Where a committed text stands

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

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

PUBLISHED_KEYS

The key the chain started under, as this build of agentkit knows it.

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

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.

data_hash

SHA-256 over canonical_json

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.

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

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

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