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). 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.
• KeyRotation (KEY-) moves the chain to a new signing key. A routine rotation is signed by the old key; a compromise declaration is signed by the new one and is authentic only if that key is in the verifier’s out-of-band KeyAnchor, which is what makes a key thief visible rather than authoritative. See verify_chain.

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;

Structs

Amendment

The data of an amendment entry: what an earlier entry now means.

AmendmentNotice

What a reader needs next to an amended entry

EntryVerdict

The verdict on one entry

Envelope

The fields an entry’s hash commits to

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 keys a verifier trusts out of band — the half of the trust model the chain cannot supply, because a chain signed end to end by a thief is internally perfect.

KeyRotation

The data of a key_rotation entry.

PublicKeyHex

An Ed25519 public key, hex on the wire

Redaction

What a AmendmentKind::Redaction removed, and what is left

RotationStatement

What the proof of possession signs

Sha256Hex

A SHA-256 digest, hex on the wire

SignatureHex

An Ed25519 signature, hex on the wire

TrustedHead

The last entry the compromised key is trusted for

Enums

AmendmentError

An amendment is malformed

LinkError

Why one link failed on its own, before chain context

RedactError

A JSON pointer in a Redaction does not resolve

RotationError

A rotation is malformed, unauthenticated, or inconsistent with the chain

RotationReason

Why the key changed

Constants

AMENDMENT_VERSION

The Amendment payload version this module produces and verifies

ENVELOPE_VERSION

The envelope version this module produces and verifies

KEY_ROTATION_VERSION

The KeyRotation payload version this module produces and verifies

PUBLISHED_KEYS

The governance signing keys this build of agentkit trusts, oldest first.

RETROACTIVE_AFTER

An attestation signed more than this long after its entry was recorded is retroactive

Functions

attest

Attest an entry: the one construction path for GovernanceAttestation, used by the server at insert and by tests building fixtures.

canonical_json

value as compact JSON with object keys sorted bytewise at every level.

data_hash

SHA-256 over canonical_json

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

kind_standing

What an amendment does to the Standing of the entry it names, when it changes it at all

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 it declares and trusting anchor for the ones the chain cannot prove.

verify_data

true when data is what link attested

verify_link

Verify one link in isolation: version, hash recomputation, signature