agora_agentkit/

govlog.rs

//! 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
//!
//! ```text
//! 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](AmendmentKind::OBLIGATION) 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.
//!
//! A sixth, a [`TestEntry`] (`TEST-`), is what a test sitting would have
//! decided, wrapped so it binds nothing: the inner entry's type and data
//! beside a title, a description and the test proposal's post. No verifier
//! reads it; readers label it [`TEST_LABEL`] wherever it appears.
//!
//! 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.

use crate::crypto::{self, Signature, SigningKey, VerifyingKey};
use crate::enums::GovernanceLogEntryType;
use crate::ids::{GovernanceLogId, GovernanceLogPrefix};
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::collections::{HashMap, HashSet};

pub use crate::enums::{AmendmentKind, CitationRelation, KeyStatus, Standing};

mod texts;
pub use texts::{
    AmendmentText, AmendmentTextStatus, AmendmentTexts, CommittedText,
    TextCommitment, TextStatus, WITHHELD_TEXT,
};

mod council;
pub use council::{
    Abstention, AgendaRanking, Asked, Ballot, BatchedQuestion, BlankStatement,
    CouncilAttachment, CouncilDecisionRecord, CouncilMember, CouncilRound,
    CouncilSeat, CouncilVote, DEFERRING_SEATS, Decided, DecisionCategory,
    DecisionSummary, FinalRoundError, FinalVotes, NotASeatChoice,
    PlacedProposal, Question, RECUSED_ACCEPTORS, RECUSED_DEFERRED_TAG,
    Rationale, RecordRuleError, RecusalVote, STEWARD_RECUSED_TAG,
    SUMMARY_POINTER, SUMMARY_WRITER, SeatChoice, SeatModels, SeatQuestions,
    SeatRanking, SeatResponse, SeatVote, SeatVotes, Statement,
    StewardEmergency, StewardRecusal, StewardVote, SummaryAcceptance,
    SummaryAuthorship, Testimony, Unanswered, Unheard, Vote, Votes, Witness,
    WitnessBatch, WitnessQuestion, WitnessSource, served_summary,
    test_labelled, testimony_attachment_name,
};

mod redactable;
pub use redactable::{REDACTION_MARKER_PATTERN, Redactable};

pub mod reading;

/// RFC 6902, as [`Revision::patch`] uses it: re-exported so callers name
/// the same types this crate was built with
pub use json_patch;

mod obligation;
pub use obligation::request;
pub mod quote;
pub use obligation::{
    Evidence, KnownEntry, OBLIGATION_VERSION, Obligation, ObligationData,
    ObligationError, ObligationRuleError, ObligationState, ObligationUpdate,
    Until,
};

mod data_set;
pub use data_set::{
    DATA_SET_VERSION, DataFile, DataFileMismatch, DataFilePath,
    DataFilePathError, DataRepoName, DataRepoNameError, DataSet,
    DataSetLookupError, DataSetLookupFailure, DataSetTarget,
    MAX_DATA_FILE_BYTES, MAX_WHOLE_READ_BYTES,
};

mod data_read;
pub use data_read::{
    DataCitation, DataCitationError, GitCommitPrefix, LineRange,
    LineRangeError, LineSpan, PastEnd, count_lines,
};

mod test_entry;
pub use test_entry::{
    TEST_ENTRY_VERSION, TEST_INNER_POINTER, TEST_LABEL, TEST_MACHINE_FIELDS,
    TestEntry, TestEntryError, decision_data, decision_type,
};

mod record;
pub use record::{
    RecordAttachment, RecordParticipant, STEWARD_RECORD_VERSION, StewardRecord,
};

mod root;
pub use root::{
    CertPurpose, CertificateError, KEY_CERT_VERSION, KeyCertStatement,
    KeyCertificate, ROOT_DOMAIN, ROOT_KEYS, ROOT_THRESHOLD, RootSet,
    RootSignature,
};

/// The shared test vectors in `vectors/govlog`; see [`vectors`]
#[cfg(test)]
mod vectors;

/// The envelope version this module produces and verifies
pub const ENVELOPE_VERSION: u32 = 1;

/// An attestation signed more than this long after its entry was recorded
/// is [retroactive](is_retroactive)
pub const RETROACTIVE_AFTER: chrono::Duration = chrono::Duration::seconds(60);

// ---------------------------------------------------------------------------
// Fixed-size hex newtypes
// ---------------------------------------------------------------------------

/// A hex string of the wrong length or alphabet for the type it was parsed
/// into
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error("{type_name}: expected {expected} bytes of hex, got {got:?}")]
pub struct HexLengthError {
    pub type_name: &'static str,
    pub expected: usize,
    pub got: String,
}

macro_rules! hex_bytes {
    ($(#[$meta:meta])* $name:ident, $len:expr) => {
        $(#[$meta])*
        #[derive(Clone, Copy, PartialEq, Eq, Hash)]
        #[cfg_attr(feature = "sqlx", derive(sqlx::Type))]
        #[cfg_attr(feature = "sqlx", sqlx(transparent))]
        pub struct $name([u8; $len]);

        impl $name {
            /// The raw bytes
            pub fn as_bytes(&self) -> &[u8; $len] {
                &self.0
            }

            /// Lowercase hex, as on the wire
            pub fn to_hex(&self) -> String {
                hex::encode(self.0)
            }
        }

        impl From<[u8; $len]> for $name {
            fn from(bytes: [u8; $len]) -> Self {
                Self(bytes)
            }
        }

        impl TryFrom<&[u8]> for $name {
            type Error = HexLengthError;

            fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
                <[u8; $len]>::try_from(bytes).map(Self).map_err(|_| {
                    HexLengthError {
                        type_name: stringify!($name),
                        expected: $len,
                        got: hex::encode(bytes),
                    }
                })
            }
        }

        impl TryFrom<Vec<u8>> for $name {
            type Error = HexLengthError;

            fn try_from(bytes: Vec<u8>) -> Result<Self, Self::Error> {
                Self::try_from(bytes.as_slice())
            }
        }

        impl std::str::FromStr for $name {
            type Err = HexLengthError;

            fn from_str(s: &str) -> Result<Self, Self::Err> {
                let bytes = hex::decode(s.trim()).map_err(|_| HexLengthError {
                    type_name: stringify!($name),
                    expected: $len,
                    got: s.to_string(),
                })?;
                Self::try_from(bytes.as_slice())
            }
        }

        impl std::fmt::Display for $name {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.write_str(&self.to_hex())
            }
        }

        impl std::fmt::Debug for $name {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                write!(f, "{}({})", stringify!($name), self.to_hex())
            }
        }

        impl Serialize for $name {
            fn serialize<S: serde::Serializer>(
                &self,
                s: S,
            ) -> Result<S::Ok, S::Error> {
                s.serialize_str(&self.to_hex())
            }
        }

        impl<'de> Deserialize<'de> for $name {
            fn deserialize<D: serde::Deserializer<'de>>(
                d: D,
            ) -> Result<Self, D::Error> {
                let s = String::deserialize(d)?;
                s.parse().map_err(serde::de::Error::custom)
            }
        }

        // Hand-written for the same reason as every id newtype: a derived
        // schema becomes a `$ref` into `$defs`, which the Claude.ai MCP
        // connector mangles (see CLAUDE.md in the agora repo).
        #[cfg(feature = "schemars")]
        impl schemars::JsonSchema for $name {
            fn inline_schema() -> bool {
                true
            }

            fn schema_name() -> std::borrow::Cow<'static, str> {
                std::borrow::Cow::Borrowed(stringify!($name))
            }

            fn schema_id() -> std::borrow::Cow<'static, str> {
                std::borrow::Cow::Borrowed(concat!(
                    module_path!(),
                    "::",
                    stringify!($name)
                ))
            }

            fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
                schemars::json_schema!({
                    "type": "string",
                    "pattern": format!("^[0-9a-f]{{{}}}$", $len * 2),
                    "description": format!("{} bytes, lowercase hex", $len),
                })
            }
        }
    };
}

hex_bytes!(
    /// A SHA-256 digest, hex on the wire
    Sha256Hex,
    32
);

hex_bytes!(
    /// An Ed25519 signature, hex on the wire
    SignatureHex,
    64
);

hex_bytes!(
    /// An Ed25519 public key, hex on the wire
    PublicKeyHex,
    32
);

hex_bytes!(
    /// A git commit id (SHA-1), hex on the wire: what a [`DataSet`] is
    /// pinned to (0.91)
    GitCommitId,
    20
);

hex_bytes!(
    /// A blinding value: 32 random bytes carried in a redactable entry's
    /// `data` under [`BLIND_KEY`]. See [`blind_data`] for what it is for.
    Blind,
    32
);

hex_bytes!(
    /// The salt of a [`TextCommitment`]: 32 random bytes kept beside the
    /// text, and deleted with it
    TextSalt,
    32
);

impl Blind {
    /// A fresh value from the operating system's random source
    pub fn random() -> Self {
        use rand::RngCore;
        let mut bytes = [0u8; 32];
        rand::rngs::OsRng.fill_bytes(&mut bytes);
        Self(bytes)
    }
}

impl TextSalt {
    /// A fresh value from the operating system's random source
    pub fn random() -> Self {
        Self(*Blind::random().as_bytes())
    }
}

impl From<Signature> for SignatureHex {
    fn from(sig: Signature) -> Self {
        Self(sig.to_bytes())
    }
}

impl From<&SignatureHex> for Signature {
    fn from(sig: &SignatureHex) -> Self {
        Signature::from_bytes(&sig.0)
    }
}

impl From<&VerifyingKey> for PublicKeyHex {
    fn from(key: &VerifyingKey) -> Self {
        Self(key.to_bytes())
    }
}

impl PublicKeyHex {
    /// The key, if the bytes are a valid curve point
    pub fn to_verifying_key(
        &self,
    ) -> Result<VerifyingKey, ed25519_dalek::SignatureError> {
        VerifyingKey::from_bytes(&self.0)
    }
}

// ---------------------------------------------------------------------------
// Canonical JSON and hashing
// ---------------------------------------------------------------------------

/// `value` as compact JSON with object keys sorted bytewise at every level.
///
/// `serde_json::to_vec` on a [`serde_json::Value`] is *not* canonical:
/// with the `preserve_order` feature (on in every Agora workspace, off in
/// this crate's own tests) objects serialize in insertion order, so the
/// same value hashes differently depending on who built it. Strings and
/// numbers use serde_json's own formatting, which is deterministic for a
/// given value.
pub fn canonical_json(value: &serde_json::Value) -> Vec<u8> {
    let mut out = Vec::new();
    write_canonical(value, &mut out);
    out
}

fn write_canonical(value: &serde_json::Value, out: &mut Vec<u8>) {
    use serde_json::Value;
    match value {
        Value::Null => out.extend_from_slice(b"null"),
        Value::Bool(b) => {
            out.extend_from_slice(if *b { b"true" } else { b"false" })
        }
        Value::Number(n) => serde_json::to_writer(&mut *out, n)
            .expect("a number always serializes"),
        Value::String(s) => serde_json::to_writer(&mut *out, s)
            .expect("a string always serializes"),
        Value::Array(items) => {
            out.push(b'[');
            for (i, item) in items.iter().enumerate() {
                if i > 0 {
                    out.push(b',');
                }
                write_canonical(item, out);
            }
            out.push(b']');
        }
        Value::Object(map) => {
            let mut keys: Vec<&String> = map.keys().collect();
            keys.sort_unstable();
            out.push(b'{');
            for (i, key) in keys.into_iter().enumerate() {
                if i > 0 {
                    out.push(b',');
                }
                serde_json::to_writer(&mut *out, key)
                    .expect("a string always serializes");
                out.push(b':');
                write_canonical(&map[key], out);
            }
            out.push(b'}');
        }
    }
}

/// The RFC 6901 pointer to the first number in `data` that is not a 64-bit
/// integer, if there is one.
///
/// Governance `data` never contains one. [`canonical_json`] writes a number
/// the way `serde_json` does, and how that prints a float has changed
/// between releases (`1e21` became `1e+21`); an integer past `u64` is a
/// float to it as well, and its float parsing is not exactly rounded. A
/// hash that is meant to be permanent cannot depend on any of that, so the
/// writer refuses such `data` ([`blind_data`], [`redact_data`]) and a
/// verifier reports it without hashing it. A fraction goes in a string.
pub fn non_integer_number(data: &serde_json::Value) -> Option<String> {
    fn find(value: &serde_json::Value, path: &mut String) -> bool {
        use serde_json::Value::{Array, Number, Object};
        let mark = path.len();
        match value {
            Number(n) => return n.is_f64(),
            Array(items) => {
                for (i, item) in items.iter().enumerate() {
                    path.push_str(&format!("/{i}"));
                    if find(item, path) {
                        return true;
                    }
                    path.truncate(mark);
                }
            }
            Object(map) => {
                for (key, item) in map {
                    path.push('/');
                    path.push_str(&escape_pointer_token(key));
                    if find(item, path) {
                        return true;
                    }
                    path.truncate(mark);
                }
            }
            _ => {}
        }
        false
    }
    let mut path = String::new();
    find(data, &mut path).then_some(path)
}

/// 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)
pub fn escape_pointer_token(token: &str) -> String {
    token.replace('~', "~0").replace('/', "~1")
}

/// One escaped JSON Pointer token, unescaped: the inverse of
/// [`escape_pointer_token`] (0.74)
pub fn unescape_pointer_token(token: &str) -> String {
    token.replace("~1", "/").replace("~0", "~")
}

/// A JSON Pointer's reference tokens, unescaped. `""` (the whole
/// document) has none (0.74)
pub fn pointer_tokens(pointer: &str) -> Vec<String> {
    pointer
        .split('/')
        .skip(1)
        .map(unescape_pointer_token)
        .collect()
}

/// SHA-256 over [`canonical_json`]
pub fn data_hash(data: &serde_json::Value) -> Sha256Hex {
    Sha256Hex(Sha256::digest(canonical_json(data)).into())
}

/// The fields an entry's hash commits to
///
/// A struct rather than a [`serde_json::Value`] so the preimage serializes
/// in declaration order whatever `preserve_order` says.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct Envelope {
    /// Always [`ENVELOPE_VERSION`]
    pub agora_governance_log: u32,
    pub id: GovernanceLogId,
    pub entry_type: GovernanceLogEntryType,
    /// Unix microseconds — the precision Postgres stores
    pub created_at: i64,
    pub prev_hash: Option<Sha256Hex>,
    pub data_hash: Sha256Hex,
}

impl Envelope {
    /// The version-1 envelope for these fields
    pub fn new(
        id: GovernanceLogId,
        entry_type: GovernanceLogEntryType,
        created_at: DateTime<Utc>,
        prev_hash: Option<Sha256Hex>,
        data_hash: Sha256Hex,
    ) -> Self {
        Self {
            agora_governance_log: ENVELOPE_VERSION,
            id,
            entry_type,
            created_at: created_at.timestamp_micros(),
            prev_hash,
            data_hash,
        }
    }

    /// `created_at` as a timestamp again
    pub fn created_at(&self) -> DateTime<Utc> {
        DateTime::from_timestamp_micros(self.created_at)
            .expect("an Envelope only ever holds an in-range timestamp")
    }

    /// The bytes that are hashed
    pub fn preimage(&self) -> Vec<u8> {
        serde_json::to_vec(self).expect("an Envelope always serializes")
    }

    /// SHA-256 over [`preimage`](Self::preimage)
    pub fn entry_hash(&self) -> Sha256Hex {
        Sha256Hex(Sha256::digest(self.preimage()).into())
    }
}

/// `t` with anything below a microsecond dropped, so the value hashed is the
/// value Postgres will store
pub fn truncate_to_micros(t: DateTime<Utc>) -> DateTime<Utc> {
    DateTime::from_timestamp_micros(t.timestamp_micros())
        .expect("a timestamp that came from a DateTime is in range")
}

/// `t` with anything below a second dropped, so `signed_at` round-trips to
/// the integer the signature covers
pub fn truncate_to_seconds(t: DateTime<Utc>) -> DateTime<Utc> {
    DateTime::from_timestamp(t.timestamp(), 0)
        .expect("a timestamp that came from a DateTime is in range")
}

/// `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
pub fn is_retroactive(
    created_at: DateTime<Utc>,
    signed_at: DateTime<Utc>,
) -> bool {
    signed_at - created_at > RETROACTIVE_AFTER
}

// ---------------------------------------------------------------------------
// Wire types
// ---------------------------------------------------------------------------

/// What the server attests about one governance log entry
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct GovernanceAttestation {
    /// Envelope version; see the module docs for what `1` commits to
    pub envelope_version: u32,
    /// Position in the chain, from 1. An index, not part of the envelope:
    /// the `prev_hash` links are what prove order.
    pub chain_seq: u64,
    /// `entry_hash` of the previous entry; `null` only for the first
    pub prev_hash: Option<Sha256Hex>,
    /// SHA-256 of the entry's canonical `data`
    pub data_hash: Sha256Hex,
    /// SHA-256 of the envelope; what the signature covers
    pub entry_hash: Sha256Hex,
    /// Ed25519 over `entry_hash` and `signed_at`, by the platform's
    /// governance signing key
    pub signature: SignatureHex,
    /// When the signature was made. Distinct from `created_at`: see
    /// `retroactive`.
    pub signed_at: DateTime<Utc>,
    /// `true` when signed well after the entry was recorded — the entries
    /// that predate signing were attested this way, which proves the
    /// Steward vouches for them, not that they were signed at the time
    pub retroactive: bool,
}

/// 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
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct GovernanceChainLink {
    pub id: GovernanceLogId,
    pub entry_type: GovernanceLogEntryType,
    pub created_at: DateTime<Utc>,
    pub attestation: GovernanceAttestation,
    /// Present for `amendment` and `key_rotation` entries, whose content
    /// is what the chain means and is small by construction. A Council
    /// transcript is neither, and is read one entry at a time instead.
    /// [`verify_chain`] hashes this raw value against `data_hash` before
    /// reading it, so unknown future fields neither break an older
    /// verifier nor escape the signature.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub data: Option<serde_json::Value>,
    /// The texts a version 2 [`Amendment`] commits to, as far as the
    /// platform still holds them. Outside the envelope on purpose: a text
    /// can be erased without the chain changing.
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "read_as_written"
    )]
    pub texts: Option<AmendmentTexts>,
}

/// The platform's governance signing key, as `GET
/// /api/governance/signing-key` publishes it
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct GovernanceSigningKey {
    /// Always `"ed25519"`
    pub algorithm: String,
    pub public_key: PublicKeyHex,
    /// The envelope version entries are currently signed under
    pub envelope_version: u32,
}

impl GovernanceSigningKey {
    /// The published form of `key`
    pub fn new(key: &VerifyingKey) -> Self {
        Self {
            algorithm: "ed25519".to_string(),
            public_key: key.into(),
            envelope_version: ENVELOPE_VERSION,
        }
    }
}

// ---------------------------------------------------------------------------
// Amendments
// ---------------------------------------------------------------------------

/// 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.
pub const AMENDMENT_VERSION: u32 = 2;

/// An amendment is malformed
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum AmendmentError {
    #[error("agora_governance_amendment is {0}, not 1 or {AMENDMENT_VERSION}")]
    UnsupportedVersion(u32),
    #[error(
        "a version 1 amendment carries its texts and a version \
         {AMENDMENT_VERSION} one commits to them; this does neither \
         consistently"
    )]
    TextShape,
    #[error("`{0}` beside the entry is not the text the entry committed to")]
    TextMismatch(&'static str),
    #[error("texts beside an entry that commits to none")]
    UncommittedText,
    #[error("kind `redaction` requires a `redaction`")]
    MissingRedaction,
    #[error("`redaction` is only valid on kind `redaction`")]
    UnexpectedRedaction,
    #[error("kind `revision` requires a `revision`")]
    MissingRevision,
    #[error("`revision` is only valid on kind `revision`")]
    UnexpectedRevision,
    #[error("the `revision` is malformed: {0}")]
    RevisionShape(ReviseError),
    #[error("kind `{0}` requires an `update`")]
    MissingUpdate(AmendmentKind),
    #[error("`update` is only valid on the obligation kinds")]
    UnexpectedUpdate,
    #[error("an `update` of kind `{update}` on an amendment of kind `{kind}`")]
    UpdateMismatch {
        kind: AmendmentKind,
        update: AmendmentKind,
    },
    #[error(
        "kind `{kind}` is only valid on an obligation, and {target} is not one"
    )]
    NotAnObligation {
        kind: AmendmentKind,
        target: GovernanceLogId,
    },
    #[error(
        "kind `{0}` changes precedential force, which an obligation does not have"
    )]
    PrecedentialOnObligation(AmendmentKind),
    #[error(
        "a revision of an obligation may not touch `{0}`; its status and \
         deadline change only through the obligation kinds"
    )]
    FixedObligationField(String),
    #[error("amendment target {0} is not an entry of this chain")]
    UnknownTarget(GovernanceLogId),
    #[error("amendment target {0} is not an earlier entry")]
    ForwardReference(GovernanceLogId),
    #[error("target_entry_hash is not {0}'s entry_hash")]
    WrongTargetHash(GovernanceLogId),
}

/// The `data` of an `amendment` entry: what an earlier entry now means.
///
/// The target is never edited — except its `data` under a [`Redaction`] —
/// so the amendment is the whole record of the change, and both are
/// signed links of the same chain.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct Amendment {
    /// Always [`AMENDMENT_VERSION`]
    pub agora_governance_amendment: u32,
    pub target: GovernanceLogId,
    /// The target's `entry_hash` — binds this to one exact entry
    pub target_entry_hash: Sha256Hex,
    pub kind: AmendmentKind,
    /// The governance entry that authorizes this, when one does
    /// (e.g. `GOV-2026-0005`). `None` for a lawful-deletion redaction.
    #[serde(default)]
    pub authority: Option<GovernanceLogId>,
    /// Section or legal basis, human-readable: `"§1 (Red Team Cases
    /// Recharacterized)"`, `"GDPR Art. 17(1)(a)"`. Never personal data —
    /// and erasable, for the day that rule is broken.
    pub basis: AmendmentText,
    /// The label readers and prompts show next to the target
    pub note: AmendmentText,
    /// Why, at length — `note` is the label, this is the reasoning.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rationale: Option<AmendmentText>,
    /// Present iff `kind` is [`AmendmentKind::Redaction`]
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub redaction: Option<Redaction>,
    /// Present iff `kind` is [`AmendmentKind::Revision`] (0.43)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub revision: Option<Revision>,
    /// Present iff `kind` is one of [`AmendmentKind::OBLIGATION`], and of
    /// that kind (0.72)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub update: Option<ObligationUpdate>,
}

/// What a [`AmendmentKind::Redaction`] removed, and what is left
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct Redaction {
    /// RFC 6901 JSON pointers into the target's `data` whose values were
    /// replaced. Paths only: never the removed content, never the subject.
    pub fields: Vec<String>,
    /// What the target's `data` hashes to after redaction, so the redacted
    /// content is itself verifiable and cannot be altered again silently
    pub resulting_data_hash: Sha256Hex,
    /// What the target's [`latest`] version hashes to after redaction: its
    /// [`Revision`]s rebased over the redacted data. `None` when it has
    /// none. (0.43)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub resulting_latest_hash: Option<Sha256Hex>,
}

/// A commit on a governance entry: an RFC 6902 patch from its previous
/// version to the next.
///
/// Nothing is overwritten. The entry keeps the `data` it was signed with,
/// and its [`latest`] version is derived by applying every revision's
/// patch in chain order, as git derives a checkout from its commits. See
/// [`AmendmentDraft::revision`].
///
/// A value a patch adds (`add`, `replace`, `test`) lives in the amendment,
/// which redaction cannot reach yet; removals, moves and copies carry no
/// content.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Revision {
    /// From the previous version to this one
    pub patch: json_patch::Patch,
    /// For each `remove` of a duplicate, the removed path and the path it
    /// duplicated: what a later redaction of the one must also erase from
    /// the stored original. Not `test` ops, which would carry the values.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub duplicates: Vec<(String, String)>,
    /// What the entry's `data` hashes to after `patch`
    pub resulting_data_hash: Sha256Hex,
}

/// What a [`Revision`] changes, before it is applied: a patch, and the
/// duplicates it removes, if that is what it does
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Edit {
    pub patch: json_patch::Patch,
    /// See [`Revision::duplicates`]
    pub duplicates: Vec<(String, String)>,
}

impl From<json_patch::Patch> for Edit {
    fn from(patch: json_patch::Patch) -> Self {
        Self {
            patch,
            duplicates: Vec::new(),
        }
    }
}

/// Written by hand: `json_patch` derives nothing inline, and a `$ref` in
/// a schema is not an option (see the agora CLAUDE.md)
#[cfg(feature = "schemars")]
impl schemars::JsonSchema for Revision {
    fn inline_schema() -> bool {
        true
    }

    fn schema_name() -> std::borrow::Cow<'static, str> {
        "Revision".into()
    }

    fn json_schema(
        generator: &mut schemars::SchemaGenerator,
    ) -> schemars::Schema {
        let hash = generator.subschema_for::<Sha256Hex>();
        schemars::json_schema!({
            "type": "object",
            "properties": {
                "patch": {
                    "description": "RFC 6902 JSON Patch from the previous version to this one",
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "op": {
                                "type": "string",
                                "enum": ["add", "remove", "replace", "move", "copy", "test"]
                            },
                            "path": {"type": "string"},
                            "from": {"type": "string"},
                            "value": true
                        },
                        "required": ["op", "path"]
                    }
                },
                "duplicates": {
                    "description": "(removed path, the path it duplicated) for each duplicate removed",
                    "type": "array",
                    "items": {
                        "type": "array",
                        "items": {"type": "string"},
                        "minItems": 2,
                        "maxItems": 2
                    }
                },
                "resulting_data_hash": hash
            },
            "required": ["patch", "resulting_data_hash"]
        })
    }
}

impl Revision {
    /// Everything wrong with it that is checkable without `data`: an empty
    /// patch, or a duplicate the patch does not remove
    pub fn validate(&self) -> Result<(), ReviseError> {
        if self.patch.is_empty() {
            return Err(ReviseError::EmptyPatch);
        }
        for (path, _) in &self.duplicates {
            let removed = self.patch.iter().any(|op| {
                matches!(op, json_patch::PatchOperation::Remove(r) if r.path.as_str() == path)
            });
            if !removed {
                return Err(ReviseError::NotRemoved(path.clone()));
            }
        }
        Ok(())
    }

    /// An [`Edit`] removing each `(path, same_as)` pair's `path`, whose
    /// value is byte-identical (as [`canonical_json`]) to `same_as`'s,
    /// which it leaves in place
    pub fn remove_duplicates(
        data: &serde_json::Value,
        pairs: &[(&str, &str)],
    ) -> Result<Edit, ReviseError> {
        let mut ops = Vec::with_capacity(pairs.len());
        for (path, _) in pairs {
            let path = json_patch::jsonptr::PointerBuf::parse(*path)
                .map_err(|e| ReviseError::Patch(e.to_string()))?;
            ops.push(json_patch::PatchOperation::Remove(
                json_patch::RemoveOperation { path },
            ));
        }
        let edit = Edit {
            patch: json_patch::Patch(ops),
            duplicates: pairs
                .iter()
                .map(|(p, s)| (p.to_string(), s.to_string()))
                .collect(),
        };
        check_duplicates(data, &edit)?;
        Ok(edit)
    }
}

/// Each of `edit`'s duplicates is removed by its patch, was byte-identical
/// to its `same_as`, and its `same_as` survives the patch unchanged
fn check_duplicates(
    data: &serde_json::Value,
    edit: &Edit,
) -> Result<(), ReviseError> {
    for (path, same_as) in &edit.duplicates {
        let resolve = |pointer: &str| {
            data.pointer(pointer)
                .ok_or_else(|| ReviseError::Unresolved(pointer.to_string()))
        };
        let (removed, kept) = (resolve(path)?, resolve(same_as)?);
        if canonical_json(removed) != canonical_json(kept) {
            return Err(ReviseError::NotIdentical {
                path: path.clone(),
                same_as: same_as.clone(),
            });
        }
    }
    let revised = apply_patch(data, &edit.patch)?;
    for (path, same_as) in &edit.duplicates {
        let kept = data.pointer(same_as);
        let removes = |op: &json_patch::PatchOperation| matches!(op, json_patch::PatchOperation::Remove(r) if r.path.as_str() == path);
        if !edit.patch.iter().any(removes) {
            return Err(ReviseError::NotRemoved(path.clone()));
        }
        let survives = revised.pointer(same_as).is_some_and(|v| {
            kept.is_some_and(|k| canonical_json(v) == canonical_json(k))
        });
        if !survives {
            return Err(ReviseError::SourceRemoved {
                path: path.clone(),
                same_as: same_as.clone(),
            });
        }
    }
    Ok(())
}

/// An [`Amendment`] and the texts it commits to: what a writer appends,
/// the first as the entry's `data` and the second beside it
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AmendmentDraft {
    pub amendment: Amendment,
    pub texts: AmendmentTexts,
}

impl AmendmentDraft {
    /// An amendment of `kind` against `target`.
    ///
    /// Redactions and revisions go through [`redaction`](Self::redaction)
    /// and [`revision`](Self::revision) instead, the only ways to get
    /// a `resulting_data_hash` of data that actually exists. A `&str` or `String`
    /// text gets a [random](TextSalt::random) salt.
    pub fn new(
        target: GovernanceLogId,
        target_entry_hash: Sha256Hex,
        kind: AmendmentKind,
        basis: impl Into<CommittedText>,
        note: impl Into<CommittedText>,
    ) -> Result<Self, AmendmentError> {
        match kind {
            AmendmentKind::Redaction => {
                return Err(AmendmentError::MissingRedaction);
            }
            AmendmentKind::Revision => {
                return Err(AmendmentError::MissingRevision);
            }
            k if k.is_obligation() => {
                return Err(AmendmentError::MissingUpdate(k));
            }
            _ => {}
        }
        let (basis, note) = (basis.into(), note.into());
        Ok(Self {
            amendment: Amendment {
                agora_governance_amendment: AMENDMENT_VERSION,
                target,
                target_entry_hash,
                kind,
                authority: None,
                basis: AmendmentText::Committed(basis.commitment()),
                note: AmendmentText::Committed(note.commitment()),
                rationale: None,
                redaction: None,
                revision: None,
                update: None,
            },
            texts: AmendmentTexts {
                basis: Some(basis),
                note: Some(note),
                rationale: None,
            },
        })
    }

    /// A redaction of `fields` from the target's `data`, with the redacted
    /// data it commits to.
    ///
    /// `amendment_id` is the id this amendment will be appended under: the
    /// marker left behind names it, so the redaction says who ordered it.
    /// Append both together or neither — the returned `data` is what the
    /// target's row must hold for [`verify_chain`] to accept it. `blind`
    /// is the target's new [`Blind`]: [random](Blind::random), so a
    /// rehearsal's `resulting_data_hash` is not the real one's.
    ///
    /// `revisions` are the target's, in chain order. They are rebased over
    /// the redacted data, which must still take every patch, and a value
    /// they removed as a duplicate of a redacted one is redacted from the
    /// stored original too: `fields` is extended with it, or the erased
    /// text would still be readable as first signed.
    // TODO(docs/design-govlog-revisions.md): redact inside a revision's
    // patch values, before any revision adds content.
    #[allow(clippy::too_many_arguments)]
    pub fn redaction(
        amendment_id: &GovernanceLogId,
        target: GovernanceLogId,
        target_entry_hash: Sha256Hex,
        basis: impl Into<CommittedText>,
        note: impl Into<CommittedText>,
        mut fields: Vec<String>,
        data: &serde_json::Value,
        blind: Blind,
        revisions: &[&Revision],
    ) -> Result<(Self, serde_json::Value), RedactError> {
        for extra in duplicates_of(&fields, revisions) {
            let covered = fields.iter().any(|f| {
                extra.strip_prefix(f.as_str()).is_some_and(|rest| {
                    rest.is_empty() || rest.starts_with('/')
                })
            });
            if !covered && data.pointer(&extra).is_some() {
                fields.push(extra);
            }
        }
        let redacted = redact_data(data, &fields, amendment_id, blind)?;
        let resulting_latest_hash = match revisions {
            [] => None,
            _ => Some(data_hash(
                &latest(&redacted, revisions.iter().copied())
                    .map_err(|e| RedactError::Rebase(e.to_string()))?,
            )),
        };
        let (basis, note) = (basis.into(), note.into());
        Ok((
            Self {
                amendment: Amendment {
                    agora_governance_amendment: AMENDMENT_VERSION,
                    target,
                    target_entry_hash,
                    kind: AmendmentKind::Redaction,
                    authority: None,
                    basis: AmendmentText::Committed(basis.commitment()),
                    note: AmendmentText::Committed(note.commitment()),
                    rationale: None,
                    redaction: Some(Redaction {
                        fields,
                        resulting_data_hash: data_hash(&redacted),
                        resulting_latest_hash,
                    }),
                    revision: None,
                    update: None,
                },
                texts: AmendmentTexts {
                    basis: Some(basis),
                    note: Some(note),
                    rationale: None,
                },
            },
            redacted,
        ))
    }

    /// A revision of the target by `edit` (a patch, or
    /// [`Revision::remove_duplicates`]), applied to its `latest` version
    /// (see [`latest`]); returns the next version it commits to.
    ///
    /// Nothing is written to the target. A patch that adds content (`add`
    /// or `replace`) to a target without a [`Blind`] adds one too, so the
    /// public `resulting_data_hash` cannot confirm a guess at text a later
    /// redaction removes; `copy` and `move` add nothing that was not
    /// already covered by the entry's own hash. A patch may not touch an
    /// existing blind.
    pub fn revision(
        target: GovernanceLogId,
        target_type: GovernanceLogEntryType,
        target_entry_hash: Sha256Hex,
        basis: impl Into<CommittedText>,
        note: impl Into<CommittedText>,
        latest: &serde_json::Value,
        edit: impl Into<Edit>,
    ) -> Result<(Self, serde_json::Value), ReviseError> {
        let Edit {
            mut patch,
            duplicates,
        } = edit.into();
        if !is_revisable(target_type) {
            return Err(ReviseError::NotRevisable(target_type));
        }
        if patch.is_empty() {
            return Err(ReviseError::EmptyPatch);
        }
        let blind_pointer = format!("/{BLIND_KEY}");
        for op in patch.iter() {
            let from = match op {
                json_patch::PatchOperation::Move(m) => Some(m.from.as_str()),
                json_patch::PatchOperation::Copy(c) => Some(c.from.as_str()),
                _ => None,
            };
            for pointer in
                [Some(op.path().as_str()), from].into_iter().flatten()
            {
                if overlaps(pointer, &blind_pointer) {
                    return Err(ReviseError::BlindPointer(pointer.to_string()));
                }
            }
        }
        let adds = patch.iter().any(|op| {
            matches!(
                op,
                json_patch::PatchOperation::Add(_)
                    | json_patch::PatchOperation::Replace(_)
            )
        });
        if adds && latest.is_object() && latest.get(BLIND_KEY).is_none() {
            patch.0.push(json_patch::PatchOperation::Add(
                json_patch::AddOperation {
                    path: json_patch::jsonptr::PointerBuf::from_tokens([
                        BLIND_KEY,
                    ]),
                    value: Blind::random().to_hex().into(),
                },
            ));
        }
        let edit = Edit { patch, duplicates };
        check_duplicates(latest, &edit)?;
        let Edit { patch, duplicates } = edit;
        let revised = apply_patch(latest, &patch)?;
        let (basis, note) = (basis.into(), note.into());
        Ok((
            Self {
                amendment: Amendment {
                    agora_governance_amendment: AMENDMENT_VERSION,
                    target,
                    target_entry_hash,
                    kind: AmendmentKind::Revision,
                    authority: None,
                    basis: AmendmentText::Committed(basis.commitment()),
                    note: AmendmentText::Committed(note.commitment()),
                    rationale: None,
                    redaction: None,
                    revision: Some(Revision {
                        patch,
                        duplicates,
                        resulting_data_hash: data_hash(&revised),
                    }),
                    update: None,
                },
                texts: AmendmentTexts {
                    basis: Some(basis),
                    note: Some(note),
                    rationale: None,
                },
            },
            revised,
        ))
    }

    /// An amendment to an obligation, of the kind `update` is
    pub fn obligation(
        target: GovernanceLogId,
        target_entry_hash: Sha256Hex,
        update: ObligationUpdate,
        basis: impl Into<CommittedText>,
        note: impl Into<CommittedText>,
    ) -> Self {
        let (basis, note) = (basis.into(), note.into());
        Self {
            amendment: Amendment {
                agora_governance_amendment: AMENDMENT_VERSION,
                target,
                target_entry_hash,
                kind: update.kind(),
                authority: None,
                basis: AmendmentText::Committed(basis.commitment()),
                note: AmendmentText::Committed(note.commitment()),
                rationale: None,
                redaction: None,
                revision: None,
                update: Some(update),
            },
            texts: AmendmentTexts {
                basis: Some(basis),
                note: Some(note),
                rationale: None,
            },
        }
    }

    /// The draft with the governance entry that authorizes it
    pub fn with_authority(mut self, authority: GovernanceLogId) -> Self {
        self.amendment.authority = Some(authority);
        self
    }

    /// The draft with its [`rationale`](Amendment::rationale)
    pub fn with_rationale(
        mut self,
        rationale: impl Into<CommittedText>,
    ) -> Self {
        let rationale = rationale.into();
        self.amendment.rationale =
            Some(AmendmentText::Committed(rationale.commitment()));
        self.texts.rationale = Some(rationale);
        self
    }
}

impl Amendment {
    /// Version, the shape of the texts for that version, and the
    /// redaction- and revision-shape invariants — everything checkable without the rest
    /// of the chain
    pub fn validate(&self) -> Result<(), AmendmentError> {
        let plain = match self.agora_governance_amendment {
            1 => true,
            AMENDMENT_VERSION => false,
            other => return Err(AmendmentError::UnsupportedVersion(other)),
        };
        let texts =
            [Some(&self.basis), Some(&self.note), self.rationale.as_ref()];
        if texts.into_iter().flatten().any(|t| t.is_plain() != plain) {
            return Err(AmendmentError::TextShape);
        }
        match (self.kind, &self.redaction) {
            (AmendmentKind::Redaction, None) => {
                return Err(AmendmentError::MissingRedaction);
            }
            (k, Some(_)) if k != AmendmentKind::Redaction => {
                return Err(AmendmentError::UnexpectedRedaction);
            }
            _ => {}
        }
        match (self.kind, &self.revision) {
            (AmendmentKind::Revision, None) => {
                return Err(AmendmentError::MissingRevision);
            }
            (AmendmentKind::Revision, Some(r)) => {
                r.validate().map_err(AmendmentError::RevisionShape)?;
            }
            (_, Some(_)) => return Err(AmendmentError::UnexpectedRevision),
            _ => {}
        }
        match (self.kind, &self.update) {
            (kind, None) if kind.is_obligation() => {
                Err(AmendmentError::MissingUpdate(kind))
            }
            (kind, Some(_)) if !kind.is_obligation() => {
                Err(AmendmentError::UnexpectedUpdate)
            }
            (kind, Some(update)) if update.kind() != kind => {
                Err(AmendmentError::UpdateMismatch {
                    kind,
                    update: update.kind(),
                })
            }
            _ => Ok(()),
        }
    }

    /// Where each committed text stands given what is `beside` the entry;
    /// `None` for version 1, whose texts are in the signed `data`.
    ///
    /// A text that is beside the entry and is not the one committed to,
    /// or that the entry never committed to at all, is an error: someone
    /// put words next to a signed entry that the signer did not write.
    pub fn text_status(
        &self,
        beside: Option<&AmendmentTexts>,
    ) -> Result<Option<AmendmentTextStatus>, AmendmentError> {
        let empty = AmendmentTexts::default();
        let beside = beside.unwrap_or(&empty);
        let (Some(basis), Some(note)) = (
            self.basis.status(beside.basis.as_ref()),
            self.note.status(beside.note.as_ref()),
        ) else {
            return if beside.is_empty() {
                Ok(None)
            } else {
                Err(AmendmentError::UncommittedText)
            };
        };
        let rationale = match (&self.rationale, &beside.rationale) {
            (None, Some(_)) => return Err(AmendmentError::UncommittedText),
            (None, None) => None,
            (Some(text), beside) => text.status(beside.as_ref()),
        };
        for (name, status) in [
            ("basis", Some(basis)),
            ("note", Some(note)),
            ("rationale", rationale),
        ] {
            if status == Some(TextStatus::Mismatch) {
                return Err(AmendmentError::TextMismatch(name));
            }
        }
        Ok(Some(AmendmentTextStatus {
            basis,
            note,
            rationale,
        }))
    }
}

/// What an amendment does to the [`Standing`] of the entry it names, when
/// it changes it at all
pub fn kind_standing(kind: AmendmentKind) -> Option<Standing> {
    match kind {
        AmendmentKind::NonPrecedential => Some(Standing::NonPrecedential),
        AmendmentKind::Overruled => Some(Standing::Overruled),
        AmendmentKind::Superseded => Some(Standing::Superseded),
        AmendmentKind::Reinstated => Some(Standing::InForce),
        AmendmentKind::Correction
        | AmendmentKind::Redaction
        | AmendmentKind::Reattested
        | AmendmentKind::Revision
        | AmendmentKind::Planned
        | AmendmentKind::Discharged
        | AmendmentKind::Lapsed
        | AmendmentKind::Rescheduled
        | AmendmentKind::Withdrawn => None,
    }
}

/// The [`Standing`] conferred by `kinds` — the amendments naming one entry,
/// in chain order. The last one that changes standing wins.
pub fn standing(kinds: impl IntoIterator<Item = AmendmentKind>) -> Standing {
    kinds
        .into_iter()
        .filter_map(kind_standing)
        .last()
        .unwrap_or_default()
}

/// The top-level key of a redactable entry's `data` that holds its
/// [`Blind`]
pub const BLIND_KEY: &str = "_blind";

/// 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.
pub fn is_redactable(entry_type: GovernanceLogEntryType) -> bool {
    !matches!(
        entry_type,
        GovernanceLogEntryType::Amendment | GovernanceLogEntryType::KeyRotation
    )
}

/// `data` cannot be blinded
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum BlindError {
    #[error("a redactable entry's data must be a JSON object")]
    NotAnObject,
    #[error(
        "data already has a {BLIND_KEY:?} key; the writer supplies it, not the caller"
    )]
    AlreadyBlinded,
    #[error(
        "{0:?} is a number that is not a 64-bit integer; governance data \
         never contains one (put a fraction in a string)"
    )]
    NonIntegerNumber(String),
}

/// `data` with a [`Blind`] under [`BLIND_KEY`] — what a writer signs and
/// stores for every [redactable](is_redactable) entry.
///
/// An entry's `data_hash` is public and permanent: the chain cannot verify
/// without it. After a redaction everything in `data` *except* the removed
/// values is public too, so without a blind anyone could test a guess at a
/// removed value — a name, a handle — by putting it back and hashing. The
/// blind is 256 bits of the preimage that [`redact_data`] replaces along
/// with the values, so the old hash can no longer be reproduced by anyone
/// who did not already hold the unredacted entry. It is not a secret while
/// the entry is whole, and it is not part of the envelope: verifiers hash
/// `data` as they always did.
///
/// Entries written before blinding existed have none. Their first
/// redaction is only as safe as the removed values are hard to guess
/// (redact the enclosing value when in doubt); it leaves a blind behind,
/// so later ones are protected.
pub fn blind_data(
    data: &serde_json::Value,
    blind: Blind,
) -> Result<serde_json::Value, BlindError> {
    if let Some(pointer) = non_integer_number(data) {
        return Err(BlindError::NonIntegerNumber(pointer));
    }
    let mut out = data.clone();
    let object = out.as_object_mut().ok_or(BlindError::NotAnObject)?;
    if object.contains_key(BLIND_KEY) {
        return Err(BlindError::AlreadyBlinded);
    }
    object.insert(BLIND_KEY.to_string(), blind.to_hex().into());
    Ok(out)
}

/// A [`Redaction`] cannot be applied as asked
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum RedactError {
    #[error("pointer {0:?} does not resolve in the entry's data")]
    Unresolved(String),
    #[error("the empty pointer would redact the whole entry")]
    WholeEntry,
    #[error("a redaction names at least one pointer")]
    NoFields,
    #[error("{0:?} is the entry's blind; every redaction replaces it already")]
    BlindPointer(String),
    #[error("a revision no longer applies to the redacted data: {0}")]
    Rebase(String),
    #[error(
        "{0:?} is a number that is not a 64-bit integer; governance data \
         never contains one"
    )]
    NonIntegerNumber(String),
}

/// The marker a redaction leaves in place of a value
pub fn redaction_marker(amendment_id: &GovernanceLogId) -> String {
    format!("[redacted by {amendment_id}]")
}

/// `data` with the value at each RFC 6901 pointer in `fields` replaced by
/// [`redaction_marker`].
///
/// Whole-value replacement only: a redaction tool that can write arbitrary
/// replacement prose is a rewrite tool. The server and every verifier share
/// this one definition, because what it returns is what the target's
/// `resulting_data_hash` covers.
///
/// The entry's [`Blind`] is replaced by `blind` — a fresh one, not a
/// marker. Destroying the old value is what stops a removed value being
/// confirmed against the entry's original `data_hash` (see [`blind_data`]);
/// leaving a *new* one is what protects the next redaction of the same
/// entry, whose removed values could otherwise be tested against this
/// one's public `resulting_data_hash`. An entry that predates blinding
/// gains one here. `blind` must be [random](Blind::random) outside tests.
pub fn redact_data(
    data: &serde_json::Value,
    fields: &[String],
    amendment_id: &GovernanceLogId,
    blind: Blind,
) -> Result<serde_json::Value, RedactError> {
    if fields.is_empty() {
        return Err(RedactError::NoFields);
    }
    if let Some(pointer) = non_integer_number(data) {
        return Err(RedactError::NonIntegerNumber(pointer));
    }
    let blind_pointer = format!("/{BLIND_KEY}");
    let marker = serde_json::Value::String(redaction_marker(amendment_id));
    let mut out = data.clone();
    for pointer in fields {
        if pointer.is_empty() {
            return Err(RedactError::WholeEntry);
        }
        if *pointer == blind_pointer {
            return Err(RedactError::BlindPointer(pointer.clone()));
        }
        let slot = out
            .pointer_mut(pointer)
            .ok_or_else(|| RedactError::Unresolved(pointer.clone()))?;
        *slot = marker.clone();
    }
    // Every entry a writer has produced is an object. Anything else has
    // nowhere to keep a blind, and staying redactable matters more.
    if let Some(object) = out.as_object_mut() {
        object.insert(BLIND_KEY.to_string(), blind.to_hex().into());
    }
    Ok(out)
}

/// Whether entries of this type can be revised. Those that cannot be
/// [redacted](is_redactable) cannot, nor can a [`StewardRecord`]: it is
/// the disclosure of what was done to the others.
pub fn is_revisable(entry_type: GovernanceLogEntryType) -> bool {
    is_redactable(entry_type)
        && entry_type != GovernanceLogEntryType::StewardRecord
}

/// A [`Revision`] cannot be made or applied as asked
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum ReviseError {
    #[error("a revision's patch has at least one op")]
    EmptyPatch,
    #[error("the patch does not apply: {0}")]
    Patch(String),
    #[error("{0:?} is the entry's blind, which a revision never touches")]
    BlindPointer(String),
    #[error("pointer {0:?} does not resolve")]
    Unresolved(String),
    #[error("{path:?} is not byte-identical to {same_as:?}")]
    NotIdentical { path: String, same_as: String },
    #[error("{same_as:?}, which {path:?} duplicates, has to survive the patch")]
    SourceRemoved { path: String, same_as: String },
    #[error("{0:?} is listed as a duplicate the patch does not remove")]
    NotRemoved(String),
    #[error("{0} entries are never revised")]
    NotRevisable(GovernanceLogEntryType),
    #[error(
        "{0:?} is a number that is not a 64-bit integer; governance data \
         never contains one"
    )]
    NonIntegerNumber(String),
}

/// `a` and `b` name the same value, or one lies inside the other
fn overlaps(a: &str, b: &str) -> bool {
    let within = |inner: &str, outer: &str| {
        inner
            .strip_prefix(outer)
            .is_some_and(|rest| rest.is_empty() || rest.starts_with('/'))
    };
    within(a, b) || within(b, a)
}

/// `data` with `patch` applied, as the `json-patch` crate applies RFC 6902
pub fn apply_patch(
    data: &serde_json::Value,
    patch: &json_patch::Patch,
) -> Result<serde_json::Value, ReviseError> {
    let mut out = data.clone();
    json_patch::patch(&mut out, patch)
        .map_err(|e| ReviseError::Patch(e.to_string()))?;
    if let Some(pointer) = non_integer_number(&out) {
        return Err(ReviseError::NonIntegerNumber(pointer));
    }
    Ok(out)
}

/// 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.
pub fn latest<'a>(
    data: &serde_json::Value,
    revisions: impl IntoIterator<Item = &'a Revision>,
) -> Result<serde_json::Value, ReviseError> {
    let mut current = data.clone();
    for revision in revisions {
        current = apply_patch(&current, &revision.patch)?;
    }
    Ok(current)
}

/// The paths `revisions` removed as duplicates of a value in `fields` (or
/// of one inside it, or holding it): what a redaction of `fields` must
/// also erase from the stored original
fn duplicates_of(fields: &[String], revisions: &[&Revision]) -> Vec<String> {
    let mut extra = Vec::new();
    for (removed, same_as) in revisions.iter().flat_map(|r| &r.duplicates) {
        for field in fields {
            if let Some(rest) = field.strip_prefix(same_as.as_str())
                && (rest.is_empty() || rest.starts_with('/'))
            {
                // Part of the source: the same part of the copy.
                extra.push(format!("{removed}{rest}"));
            } else if overlaps(field, same_as) {
                // The whole source: the whole copy.
                extra.push(removed.clone());
            }
        }
    }
    extra
}

/// The revisions of one entry, for
/// [`check_content`](GovernanceVerification::check_content)
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct RevisionHistory {
    /// In chain order
    pub revisions: Vec<(GovernanceLogId, Revision)>,
    /// How many of them came before the entry's last redaction, which
    /// rebased them: their own hashes describe unredacted history
    pub rebased: usize,
    /// What the last redaction says the rebased ones fold to
    pub rebased_hash: Option<Sha256Hex>,
}

/// What a reader needs next to an amended entry
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct AmendmentNotice {
    pub id: GovernanceLogId,
    pub kind: AmendmentKind,
    #[serde(default)]
    pub authority: Option<GovernanceLogId>,
    pub basis: String,
    pub note: String,
    /// See [`Amendment::rationale`]
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rationale: Option<String>,
    /// See [`Amendment::update`] (0.72)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub update: Option<ObligationUpdate>,
    pub created_at: DateTime<Utc>,
}

impl AmendmentNotice {
    /// The notice for `amendment`, appended as `id` at `created_at`
    /// A text no longer `beside` the entry reads [`WITHHELD_TEXT`]
    pub fn new(
        id: GovernanceLogId,
        created_at: DateTime<Utc>,
        amendment: &Amendment,
        beside: Option<&AmendmentTexts>,
    ) -> Self {
        let beside = beside.cloned().unwrap_or_default();
        Self {
            id,
            kind: amendment.kind,
            authority: amendment.authority.clone(),
            basis: amendment.basis.resolve(beside.basis.as_ref()).into(),
            note: amendment.note.resolve(beside.note.as_ref()).into(),
            rationale: amendment
                .rationale
                .as_ref()
                .map(|r| r.resolve(beside.rationale.as_ref()).into()),
            update: amendment.update.clone(),
            created_at,
        }
    }
}

/// 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)
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct GovernanceCitation {
    pub id: GovernanceLogId,
    pub entry_type: GovernanceLogEntryType,
    pub title: String,
    pub relation: CitationRelation,
    pub created_at: DateTime<Utc>,
}

/// 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
#[derive(Debug, thiserror::Error)]
#[error("the record's {relation:?} field does not parse: {error}")]
pub struct MalformedCitation {
    /// The relation the field carries, for the caller that knows from
    /// elsewhere (a database match) that the entry does cite
    pub relation: CitationRelation,
    #[source]
    pub error: serde_json::Error,
}

/// 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)
pub fn citations_in(
    entry_type: GovernanceLogEntryType,
    data: &serde_json::Value,
) -> Result<Vec<(GovernanceLogId, CitationRelation)>, MalformedCitation> {
    #[derive(Deserialize)]
    struct Concerns {
        #[serde(default)]
        concerns: Vec<GovernanceLogId>,
    }
    #[derive(Deserialize)]
    struct Authority {
        #[serde(default)]
        authority: Option<GovernanceLogId>,
    }
    #[derive(Deserialize)]
    struct Overrules {
        #[serde(default)]
        overrules: Vec<GovernanceLogId>,
    }
    fn each(
        ids: impl IntoIterator<Item = GovernanceLogId>,
        relation: CitationRelation,
    ) -> Vec<(GovernanceLogId, CitationRelation)> {
        ids.into_iter().map(|id| (id, relation)).collect()
    }
    let malformed =
        |relation| move |error| MalformedCitation { relation, error };
    match entry_type {
        GovernanceLogEntryType::StewardRecord => {
            serde_json::from_value::<Concerns>(data.clone())
                .map(|c| each(c.concerns, CitationRelation::Concerns))
                .map_err(malformed(CitationRelation::Concerns))
        }
        GovernanceLogEntryType::Amendment => {
            serde_json::from_value::<Authority>(data.clone())
                .map(|a| each(a.authority, CitationRelation::Authority))
                .map_err(malformed(CitationRelation::Authority))
        }
        GovernanceLogEntryType::CouncilDecision => {
            serde_json::from_value::<Overrules>(data.clone())
                .map(|o| each(o.overrules, CitationRelation::Overrules))
                .map_err(malformed(CitationRelation::Overrules))
        }
        _ => Ok(Vec::new()),
    }
}

// ---------------------------------------------------------------------------
// Key rotation
// ---------------------------------------------------------------------------

/// The [`KeyRotation`] payload version this module produces and verifies
pub const KEY_ROTATION_VERSION: u32 = 2;

/// The key the chain started under, as this build of agentkit knows it.
///
/// Frozen. It predates the root keys, so until the chain's first rotation
/// carries its retroactive [`KeyCertificate`] this list is the only
/// second channel a verifier has for it; every later key is certified by
/// [`ROOT_KEYS`] instead and never appears here.
pub const PUBLISHED_KEYS: &[&str] =
    &["ebb3091dd328f1463362c171121921b2fe14628e3fc4c145deaccefb85c0e78a"];

/// Why the key changed
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[serde(rename_all = "snake_case")]
pub enum RotationReason {
    // Scheduled or voluntary; the old key signed the rotation itself.
    Routine,
    // The old key is in someone else's hands; the new key signed the
    // rotation.
    Compromise,
}

/// The last entry the compromised key is trusted for
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[serde(deny_unknown_fields)]
pub struct TrustedHead {
    pub id: GovernanceLogId,
    pub chain_seq: u64,
    pub entry_hash: Sha256Hex,
}

/// A rotation is malformed, unauthenticated, or inconsistent with the chain
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum RotationError {
    #[error("agora_governance_key_rotation is {0}, not {KEY_ROTATION_VERSION}")]
    UnsupportedVersion(u32),
    #[error("new_key is not a valid Ed25519 public key")]
    BadNewKey,
    #[error(
        "the proof of possession does not verify for this rotation at this position"
    )]
    BadProof,
    #[error("a compromise certificate must name last_trusted")]
    MissingLastTrusted,
    #[error("certificate: {0}")]
    Certificate(#[from] CertificateError),
    #[error("outgoing_certificate: {0}")]
    OutgoingCertificate(CertificateError),
    #[error(
        "the chain's first rotation must carry the genesis key's \
         outgoing_certificate"
    )]
    MissingGenesisCertificate,
    #[error(
        "outgoing_certificate belongs on the chain's first rotation and \
         nowhere else"
    )]
    UnexpectedOutgoingCertificate,
    #[error("old_key is not the key that was in force")]
    WrongOldKey,
    #[error("last_trusted does not name an earlier entry of this chain")]
    UnknownLastTrusted,
    #[error("new_key has already held this chain; a key is never brought back")]
    ReusedKey,
    #[error("last_trusted names an entry an earlier compromise repudiated")]
    RepudiatedLastTrusted,
}

/// The `data` of a `key_rotation` entry.
///
/// Build one with [`routine`](Self::routine) or
/// [`compromise`](Self::compromise): both compute the proof of possession.
/// The `certificate` is what authenticates the change; the proof only
/// shows the certified key is one somebody holds.
///
/// No free text, and unknown fields are refused: a rotation can never be
/// redacted, so it carries nothing anyone could need erased. Narrative
/// belongs in a separate, redactable entry.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[serde(deny_unknown_fields)]
pub struct KeyRotation {
    /// Always [`KEY_ROTATION_VERSION`]
    pub agora_governance_key_rotation: u32,
    pub reason: RotationReason,
    pub old_key: PublicKeyHex,
    pub new_key: PublicKeyHex,
    /// `crypto::sign(new_key, ` [`RotationStatement::hash`] `,
    /// proof_signed_at)` — the new key signing for itself, at one position
    /// in one chain
    pub proof: SignatureHex,
    /// Unix seconds; what the proof signature covers
    pub proof_signed_at: i64,
    /// The root's word that `new_key` holds the chain from here. For a
    /// compromise its statement also names the last entry trusted under
    /// `old_key`.
    pub certificate: KeyCertificate,
    /// The [`CertPurpose::Genesis`] certificate for the key the chain
    /// started under, which predates the root: on the chain's first
    /// rotation, and only there.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub outgoing_certificate: Option<KeyCertificate>,
}

/// What the proof of possession signs
///
/// A struct rather than a [`serde_json::Value`] for the same reason as
/// [`Envelope`]: declaration-ordered serialization whatever `preserve_order`
/// says. `prev_hash` is the rotation entry's own, so a proof lifted out of
/// one chain position does not verify in another.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct RotationStatement {
    /// Always [`KEY_ROTATION_VERSION`]
    pub agora_governance_key_rotation: u32,
    pub reason: RotationReason,
    pub old_key: PublicKeyHex,
    pub new_key: PublicKeyHex,
    pub prev_hash: Option<Sha256Hex>,
}

impl RotationStatement {
    /// The statement for a rotation at the position named by `prev_hash`
    pub fn new(
        reason: RotationReason,
        old_key: PublicKeyHex,
        new_key: PublicKeyHex,
        prev_hash: Option<Sha256Hex>,
    ) -> Self {
        Self {
            agora_governance_key_rotation: KEY_ROTATION_VERSION,
            reason,
            old_key,
            new_key,
            prev_hash,
        }
    }

    /// The bytes that are hashed
    pub fn preimage(&self) -> Vec<u8> {
        serde_json::to_vec(self).expect("a RotationStatement always serializes")
    }

    /// SHA-256 over [`preimage`](Self::preimage) — what the proof covers
    pub fn hash(&self) -> Sha256Hex {
        Sha256Hex(Sha256::digest(self.preimage()).into())
    }
}

impl KeyRotation {
    /// A scheduled rotation from `old_key` to `new_signing_key`.
    ///
    /// The entry itself is signed by the **old** key; entries after it
    /// verify under the new one. `prev_hash` is the rotation entry's own,
    /// and `certificate` is over [`KeyCertStatement::routine`] at it.
    pub fn routine(
        old_key: PublicKeyHex,
        new_signing_key: &SigningKey,
        prev_hash: Option<Sha256Hex>,
        now: DateTime<Utc>,
        certificate: KeyCertificate,
    ) -> Self {
        Self::build(
            RotationReason::Routine,
            old_key,
            new_signing_key,
            prev_hash,
            now,
            certificate,
        )
    }

    /// A declaration that `old_key` is compromised, trusted only through
    /// the `last_trusted` its `certificate` names.
    ///
    /// The entry is signed by the **new** key — the old one proves nothing
    /// any more. `last_trusted` must name an entry from before any earlier
    /// compromise window; a reattestation inside one restores the entry,
    /// not the ability to anchor trust there.
    pub fn compromise(
        old_key: PublicKeyHex,
        new_signing_key: &SigningKey,
        prev_hash: Option<Sha256Hex>,
        now: DateTime<Utc>,
        certificate: KeyCertificate,
    ) -> Self {
        Self::build(
            RotationReason::Compromise,
            old_key,
            new_signing_key,
            prev_hash,
            now,
            certificate,
        )
    }

    fn build(
        reason: RotationReason,
        old_key: PublicKeyHex,
        new_signing_key: &SigningKey,
        prev_hash: Option<Sha256Hex>,
        now: DateTime<Utc>,
        certificate: KeyCertificate,
    ) -> Self {
        let new_key = PublicKeyHex::from(&new_signing_key.verifying_key());
        let proof_signed_at = truncate_to_seconds(now).timestamp();
        let statement =
            RotationStatement::new(reason, old_key, new_key, prev_hash);
        let proof = crypto::sign(
            new_signing_key,
            statement.hash().as_bytes(),
            proof_signed_at,
        );
        Self {
            agora_governance_key_rotation: KEY_ROTATION_VERSION,
            reason,
            old_key,
            new_key,
            proof: proof.into(),
            proof_signed_at,
            certificate,
            outgoing_certificate: None,
        }
    }

    /// This rotation, carrying the genesis key's retroactive certificate
    pub fn with_outgoing(mut self, certificate: KeyCertificate) -> Self {
        self.outgoing_certificate = Some(certificate);
        self
    }

    /// The statement this rotation's proof covers, at `prev_hash`
    pub fn statement(&self, prev_hash: Option<Sha256Hex>) -> RotationStatement {
        RotationStatement::new(
            self.reason,
            self.old_key,
            self.new_key,
            prev_hash,
        )
    }

    /// Compromise only: the last entry trusted under `old_key`, as the
    /// root certified it
    pub fn last_trusted(&self) -> Option<&TrustedHead> {
        self.certificate.statement.last_trusted.as_ref()
    }

    /// What `certificate` must say for this rotation, appended at `seq`
    /// with `prev_hash`, to be authentic.
    ///
    /// Derived from the chain. Only `last_trusted` is taken from the
    /// certificate, because only the root can say it.
    pub fn expected_statement(
        &self,
        seq: u64,
        prev_hash: Option<Sha256Hex>,
    ) -> Result<KeyCertStatement, RotationError> {
        match self.reason {
            RotationReason::Routine => {
                Ok(KeyCertStatement::routine(self.new_key, seq, prev_hash))
            }
            RotationReason::Compromise => Ok(KeyCertStatement::compromise(
                self.new_key,
                seq,
                prev_hash,
                self.last_trusted()
                    .cloned()
                    .ok_or(RotationError::MissingLastTrusted)?,
            )),
        }
    }

    /// Version and the proof of possession at the position `prev_hash`
    /// names
    pub fn verify_proof(
        &self,
        prev_hash: Option<Sha256Hex>,
    ) -> Result<(), RotationError> {
        if self.agora_governance_key_rotation != KEY_ROTATION_VERSION {
            return Err(RotationError::UnsupportedVersion(
                self.agora_governance_key_rotation,
            ));
        }
        let new_key = self
            .new_key
            .to_verifying_key()
            .map_err(|_| RotationError::BadNewKey)?;
        crypto::verify(
            &new_key,
            self.statement(prev_hash).hash().as_bytes(),
            self.proof_signed_at,
            &Signature::from(&self.proof),
        )
        .then_some(())
        .ok_or(RotationError::BadProof)
    }

    /// [`verify_proof`](Self::verify_proof), and `certificate` is the
    /// root's for this key at this position — everything checkable
    /// without the rest of the chain
    pub fn verify_certified(
        &self,
        seq: u64,
        prev_hash: Option<Sha256Hex>,
        roots: &RootSet,
    ) -> Result<(), RotationError> {
        self.verify_proof(prev_hash)?;
        let expected = self.expected_statement(seq, prev_hash)?;
        Ok(self.certificate.verify_for(&expected, roots)?)
    }
}

/// The genesis keys a verifier trusts out of band.
///
/// Only the key the chain started under needs one: every later key is
/// certified by the [`RootSet`]. [`published`](Self::published) is this
/// build's [`PUBLISHED_KEYS`]; [`pinned`](Self::pinned) is the key a
/// client saw first and kept.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct KeyAnchor {
    keys: HashSet<PublicKeyHex>,
}

impl KeyAnchor {
    /// The keys compiled into this build of agentkit
    pub fn published() -> Self {
        PUBLISHED_KEYS
            .iter()
            .map(|k| {
                k.parse()
                    .expect("PUBLISHED_KEYS are valid 32-byte hex keys")
            })
            .collect()
    }

    /// Just the one key, as a client that pinned what it saw first trusts it
    pub fn pinned(key: PublicKeyHex) -> Self {
        std::iter::once(key).collect()
    }

    /// This anchor, plus `key`
    pub fn with(mut self, key: PublicKeyHex) -> Self {
        self.keys.insert(key);
        self
    }

    pub fn contains(&self, key: &PublicKeyHex) -> bool {
        self.keys.contains(key)
    }

    pub fn is_empty(&self) -> bool {
        self.keys.is_empty()
    }

    /// The anchored keys, in no particular order
    pub fn keys(&self) -> impl Iterator<Item = &PublicKeyHex> {
        self.keys.iter()
    }
}

impl FromIterator<PublicKeyHex> for KeyAnchor {
    fn from_iter<I: IntoIterator<Item = PublicKeyHex>>(iter: I) -> Self {
        Self {
            keys: iter.into_iter().collect(),
        }
    }
}

/// One key's span of the chain, as [`verify_chain`] derives it and
/// `GET /api/governance/signing-keys` publishes it
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct GovernanceKeyRecord {
    pub public_key: PublicKeyHex,
    /// The first `chain_seq` this key signed
    pub from_seq: u64,
    /// The last `chain_seq` this key is trusted for; `null` while active.
    /// For a compromised key this is `last_trusted`, not the seq at which
    /// the compromise was declared.
    #[serde(default)]
    pub through_seq: Option<u64>,
    pub status: KeyStatus,
    /// The rotation entry that introduced this key; `null` for the genesis
    /// key, which predates the chain
    #[serde(default)]
    pub introduced_by: Option<GovernanceLogId>,
    /// The rotation entry that ended this key's span
    #[serde(default)]
    pub retired_by: Option<GovernanceLogId>,
    /// A [`KeyCertificate`] from the root vouches for this key. `false`
    /// only for a genesis key whose retroactive certificate the chain does
    /// not carry yet.
    #[serde(default)]
    pub certified: bool,
}

/// The signing key history as `GET /api/governance/signing-keys` returns it
///
/// An object rather than a bare array: MCP structured content needs a
/// top-level object.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct GovernanceSigningKeys {
    /// Oldest first
    pub keys: Vec<GovernanceKeyRecord>,
}

/// The verdict on one entry
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct EntryVerdict {
    pub id: GovernanceLogId,
    pub chain_seq: u64,
    /// The signature verifies over `entry_hash` and `signed_at` under the
    /// published key
    pub signature_valid: bool,
    /// `entry_hash` recomputes from the envelope fields, `prev_hash` is the
    /// previous entry's `entry_hash`, and `chain_seq` is contiguous
    pub link_valid: bool,
    /// The entry's stored `data` hashes to the attested `data_hash` — or,
    /// when a redaction names the entry, to the redaction's
    /// `resulting_data_hash` — or `data` is the entry's
    /// [latest](Self::latest_data_hash) version. `null` when the
    /// verifier did not read `data`. `false` with a clean chain means the
    /// content was changed after attestation and no amendment says so.
    #[serde(default)]
    pub content_matches: Option<bool>,
    /// See [`GovernanceAttestation::retroactive`]
    pub retroactive: bool,
    /// `created_at` is earlier than the previous link's. Informational:
    /// chain order is what is attested, and a clock step does not break it.
    pub out_of_order: bool,
    /// Amendment entries that name this one
    #[serde(default)]
    pub amended_by: Vec<GovernanceLogId>,
    /// The key the signature was checked under — the one in force at this
    /// position, or for a compromise declaration the certified new key
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub signed_by: Option<PublicKeyHex>,
    /// A redaction amendment names this entry, so its `data` has lawfully
    /// changed since it was attested
    #[serde(default)]
    pub redacted: bool,
    /// What the entry's `data` must hash to now, when it has been redacted
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub redacted_data_hash: Option<Sha256Hex>,
    /// Revision amendments naming this entry, in chain order: its latest
    /// version is its stored `data` with each one's patch applied (0.43)
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub revisions: Vec<GovernanceLogId>,
    /// What the entry's [`latest`] version hashes to: the last revision's
    /// `resulting_data_hash`, or a later redaction's
    /// `resulting_latest_hash` (0.43)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub latest_data_hash: Option<Sha256Hex>,
    /// Revisions whose own `resulting_data_hash` a later redaction
    /// superseded: they describe the unredacted history, and the
    /// redaction's `resulting_latest_hash` is checked instead. Reported,
    /// not a failure. (0.43)
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub superseded_revisions: Vec<GovernanceLogId>,
    /// What [`check_content`](GovernanceVerification::check_content)
    /// folds. Not on the wire: the amendments carry it.
    #[serde(skip)]
    pub history: RevisionHistory,
    /// Signed inside a compromise window and not reattested: the key
    /// holder of record disclaims it
    #[serde(default)]
    pub repudiated: bool,
    /// [`AmendmentKind::Reattested`] amendments vouching for this entry
    /// under a later, trusted key
    #[serde(default)]
    pub reattested_by: Vec<GovernanceLogId>,
    /// A version 2 amendment's texts: each beside the entry and matching
    /// what it committed to, or withheld. A text that does not match is a
    /// `problem`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub texts: Option<AmendmentTextStatus>,
    /// What failed, when something did
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub problem: Option<String>,
}

impl EntryVerdict {
    /// Whether `data` is the stored content or the latest version. For the
    /// stored content, every revision is folded over it and checked; one
    /// that does not apply or produce its hash is a `problem`.
    fn content_check(
        &mut self,
        attested: Sha256Hex,
        data: &serde_json::Value,
    ) -> bool {
        // Never hashed: see `non_integer_number`.
        if non_integer_number(data).is_some() {
            return false;
        }
        let hash = data_hash(data);
        if hash == attested && self.redacted {
            // A copy from before the redaction: authentic, and nothing
            // later was built on it.
            return true;
        }
        if hash != attested && Some(hash) != self.redacted_data_hash {
            return Some(hash) == self.latest_data_hash;
        }
        let history = &self.history;
        let mut current = data.clone();
        let mut failures = Vec::new();
        for (i, (id, revision)) in history.revisions.iter().enumerate() {
            if i == history.rebased {
                break;
            }
            if let Some(failure) = false_duplicate(id, revision, &current) {
                failures.push(failure);
                break;
            }
            match apply_patch(&current, &revision.patch) {
                Ok(next) => current = next,
                Err(_) => {
                    failures.push(format!(
                        "revision {id} does not apply to the redacted data"
                    ));
                    break;
                }
            }
        }
        if failures.is_empty()
            && let Some(expected) = history.rebased_hash
            && data_hash(&current) != expected
        {
            failures.push(
                "the revisions rebased over the redacted data do not \
                 produce the redaction's resulting_latest_hash"
                    .to_string(),
            );
        }
        for (id, revision) in history.revisions.iter().skip(history.rebased) {
            if !failures.is_empty() {
                break;
            }
            if let Some(failure) = false_duplicate(id, revision, &current) {
                failures.push(failure);
                break;
            }
            match apply_patch(&current, &revision.patch) {
                Ok(next)
                    if data_hash(&next) == revision.resulting_data_hash =>
                {
                    current = next;
                }
                Ok(_) => failures.push(format!(
                    "revision {id} does not produce its resulting_data_hash"
                )),
                Err(_) => {
                    failures.push(format!("revision {id} does not apply"))
                }
            }
        }
        for failure in failures {
            add_problem(&mut self.problem, failure);
        }
        true
    }
}

/// Append `problem` to `problems`, once
fn add_problem(problems: &mut Option<String>, problem: String) {
    *problems = Some(match problems.take() {
        Some(p) if p.contains(&problem) => p,
        Some(p) => format!("{p}; {problem}"),
        None => problem,
    });
}

/// The first of `revision`'s duplicates that is not one in `current`, the
/// version it was applied to: what makes "nothing was lost" checkable
fn false_duplicate(
    id: &GovernanceLogId,
    revision: &Revision,
    current: &serde_json::Value,
) -> Option<String> {
    revision.duplicates.iter().find_map(|(path, same_as)| {
        let same = match (current.pointer(path), current.pointer(same_as)) {
            (Some(a), Some(b)) => canonical_json(a) == canonical_json(b),
            _ => false,
        };
        (!same).then(|| {
            format!(
                "revision {id} removed {path} as a duplicate of {same_as}, \
                 but they differ"
            )
        })
    })
}

/// A verification of the whole chain
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct GovernanceVerification {
    /// The key in force for the next entry — the active end of `keys`
    pub public_key: PublicKeyHex,
    /// Every entry's signature and link verified under the key in force,
    /// no entry's content is known to differ from what was attested, and
    /// every amendment and rotation is well-formed. Repudiated entries do
    /// not clear this by themselves: repudiation is a declared state, not
    /// a defect, and `repudiated` is where to look for it.
    pub ok: bool,
    /// The last entry in the chain
    #[serde(default)]
    pub head: Option<GovernanceLogId>,
    /// In chain order
    pub entries: Vec<EntryVerdict>,
    /// The signing key history the chain itself declares, oldest first
    #[serde(default)]
    pub keys: Vec<GovernanceKeyRecord>,
    /// The genesis key, when neither this verifier's [`KeyAnchor`] nor a
    /// [`CertPurpose::Genesis`] certificate in the chain vouches for it.
    /// Not a failure, but a reference client says so loudly. Never a later
    /// key: those are certified or they do not hold the chain at all.
    #[serde(default)]
    pub unanchored_keys: Vec<PublicKeyHex>,
    /// Entries inside a compromise window that no reattestation restored
    #[serde(default)]
    pub repudiated: Vec<GovernanceLogId>,
}

/// A [`GovernanceVerification`] without one verdict per entry: what
/// `verify_governance_log` returns unless asked for `full` (0.91.4). The
/// check behind it is the whole one; only the report is shorter.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(inline))]
pub struct GovernanceVerificationSummary {
    /// See [`GovernanceVerification::public_key`]
    pub public_key: PublicKeyHex,
    /// See [`GovernanceVerification::ok`]
    pub ok: bool,
    /// The last entry in the chain
    #[serde(default)]
    pub head: Option<GovernanceLogId>,
    /// Entries checked
    pub entries: u64,
    /// Entries whose signature did not verify
    pub signature_failures: u64,
    /// Entries whose hash link did not verify
    pub link_failures: u64,
    /// Entries whose content no longer hashes to what was attested
    pub content_mismatches: u64,
    /// Entries with a `problem`
    pub problems: u64,
    /// Entries signed well after they were recorded
    pub retroactive: u64,
    /// Entries a redaction names
    pub redacted: u64,
    /// Every entry that failed a check or has a `problem`, in chain order
    #[serde(default)]
    pub failed: Vec<GovernanceLogId>,
    /// The first of them, verdict in full
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub first_failure: Option<EntryVerdict>,
    /// See [`GovernanceVerification::keys`]
    #[serde(default)]
    pub keys: Vec<GovernanceKeyRecord>,
    /// See [`GovernanceVerification::unanchored_keys`]
    #[serde(default)]
    pub unanchored_keys: Vec<PublicKeyHex>,
    /// See [`GovernanceVerification::repudiated`]
    #[serde(default)]
    pub repudiated: Vec<GovernanceLogId>,
    pub how_to_read: String,
}

impl EntryVerdict {
    /// Whether this entry fails what [`GovernanceVerification::settle`]
    /// requires of every entry
    pub fn failed(&self) -> bool {
        !self.signature_valid
            || !self.link_valid
            || self.content_matches == Some(false)
            || self.problem.is_some()
    }
}

impl GovernanceVerification {
    /// The report without one verdict per entry (0.91.4)
    pub fn summary(&self) -> GovernanceVerificationSummary {
        let count = |f: &dyn Fn(&EntryVerdict) -> bool| -> u64 {
            self.entries.iter().filter(|e| f(e)).count() as u64
        };
        let failed: Vec<&EntryVerdict> =
            self.entries.iter().filter(|e| e.failed()).collect();
        GovernanceVerificationSummary {
            public_key: self.public_key,
            ok: self.ok,
            head: self.head.clone(),
            entries: self.entries.len() as u64,
            signature_failures: count(&|e| !e.signature_valid),
            link_failures: count(&|e| !e.link_valid),
            content_mismatches: count(&|e| e.content_matches == Some(false)),
            problems: count(&|e| e.problem.is_some()),
            retroactive: count(&|e| e.retroactive),
            redacted: count(&|e| e.redacted),
            failed: failed.iter().map(|e| e.id.clone()).collect(),
            first_failure: failed.first().map(|e| (*e).clone()),
            keys: self.keys.clone(),
            unanchored_keys: self.unanchored_keys.clone(),
            repudiated: self.repudiated.clone(),
            how_to_read: format!(
                "A summary of the whole check of {n} entries: verify_governance_log \
                 with full=true returns one verdict per entry (signature, link, \
                 content, redaction, revisions, signing key), about {kb} KB. \
                 Either way this is the server checking itself, not independent \
                 evidence; agora-agentkit's govlog::verify_chain is the \
                 independent check.",
                n = self.entries.len(),
                kb = serde_json::to_string(self).map_or(0, |s| s.len() / 1024),
            ),
        }
    }

    /// Recompute `ok` from the entries
    pub fn settle(mut self) -> Self {
        self.ok = self.entries.iter().all(|e| !e.failed());
        self
    }

    /// Record whether `data` is the content `link` attested — or what a
    /// redaction of it left behind, or its latest version. Folding its
    /// revisions over the stored content checks them too.
    ///
    /// The chain endpoint carries `data` only for amendments and
    /// rotations, so this is how a caller that read an entry in full folds
    /// that read into the report. `false` (and a `false`
    /// [`content_matches`](EntryVerdict::content_matches), which clears
    /// [`ok`](Self::ok) on the next [`settle`](Self::settle)) when the
    /// entry is not in this report at all.
    pub fn check_content(
        &mut self,
        link: &GovernanceChainLink,
        data: &serde_json::Value,
    ) -> bool {
        let Some(entry) = self.entries.iter_mut().find(|e| e.id == link.id)
        else {
            return false;
        };
        let ok = entry.content_check(link.attestation.data_hash, data);
        entry.content_matches = Some(ok);
        ok
    }
}

// ---------------------------------------------------------------------------
// Signing
// ---------------------------------------------------------------------------

/// Attest an entry: the one construction path for
/// [`GovernanceAttestation`], used by the server at insert and by tests
/// building fixtures.
///
/// `signed_at` is truncated to whole seconds, the precision the signature
/// covers; store the value the attestation carries, not the one passed in.
pub fn attest(
    key: &SigningKey,
    envelope: &Envelope,
    chain_seq: u64,
    signed_at: DateTime<Utc>,
) -> GovernanceAttestation {
    let signed_at = truncate_to_seconds(signed_at);
    let entry_hash = envelope.entry_hash();
    let signature =
        crypto::sign(key, entry_hash.as_bytes(), signed_at.timestamp());
    GovernanceAttestation {
        envelope_version: envelope.agora_governance_log,
        chain_seq,
        prev_hash: envelope.prev_hash,
        data_hash: envelope.data_hash,
        entry_hash,
        signature: signature.into(),
        signed_at,
        retroactive: is_retroactive(envelope.created_at(), signed_at),
    }
}

// ---------------------------------------------------------------------------
// Verification
// ---------------------------------------------------------------------------

/// Why one link failed on its own, before chain context
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum LinkError {
    #[error(
        "envelope version {0} is not supported (this verifier knows {ENVELOPE_VERSION})"
    )]
    UnsupportedVersion(u32),
    #[error("entry_hash does not recompute from the envelope fields")]
    HashMismatch,
    #[error("signature does not verify under the published key")]
    BadSignature,
    /// The entry's type is newer than this verifier: its envelope cannot
    /// be recomputed (the type's name is part of it), so the entry is
    /// unverifiable here rather than tampered with. Upgrade agentkit (0.91)
    #[error(
        "this entry's type is newer than this verifier, which cannot check it; \
         upgrade agora-agentkit"
    )]
    UnknownEntryType,
}

/// Recompute a link's `entry_hash` from its fields
pub fn recompute_entry_hash(link: &GovernanceChainLink) -> Sha256Hex {
    Envelope::new(
        link.id.clone(),
        link.entry_type,
        link.created_at,
        link.attestation.prev_hash,
        link.attestation.data_hash,
    )
    .entry_hash()
}

/// Verify one link in isolation: version, hash recomputation, signature
pub fn verify_link(
    link: &GovernanceChainLink,
    key: &VerifyingKey,
) -> Result<(), LinkError> {
    let a = &link.attestation;
    if a.envelope_version != ENVELOPE_VERSION {
        return Err(LinkError::UnsupportedVersion(a.envelope_version));
    }
    if link.entry_type == GovernanceLogEntryType::Unknown {
        return Err(LinkError::UnknownEntryType);
    }
    if recompute_entry_hash(link) != a.entry_hash {
        return Err(LinkError::HashMismatch);
    }
    if !crypto::verify(
        key,
        a.entry_hash.as_bytes(),
        a.signed_at.timestamp(),
        &Signature::from(&a.signature),
    ) {
        return Err(LinkError::BadSignature);
    }
    Ok(())
}

/// `true` when `data` is what `link` attested
pub fn verify_data(
    link: &GovernanceChainLink,
    data: &serde_json::Value,
) -> bool {
    data_hash(data) == link.attestation.data_hash
}

/// Whether `read`, serialized again, has the shape `written` had: an
/// object wherever it has one, an array of the same length wherever it
/// has one. Missing and `null` are the same thing.
///
/// serde's derived structs also read positionally from an array, so
/// `[]` is a perfectly good struct of optional fields and `[2, "routine",
/// …]` a perfectly good rotation. No other implementation would agree,
/// and two verifiers that disagree about what is well-formed can be shown
/// two different chains.
fn same_shape(written: &serde_json::Value, read: &serde_json::Value) -> bool {
    use serde_json::Value::{Array, Null, Object};
    match (written, read) {
        (Object(w), Object(r)) => r.iter().all(|(k, r)| match w.get(k) {
            Some(w) => same_shape(w, r),
            None => r.is_null(),
        }),
        (Array(w), Array(r)) => {
            w.len() == r.len() && w.iter().zip(r).all(|(w, r)| same_shape(w, r))
        }
        (_, Object(_) | Array(_)) => false,
        (Object(_) | Array(_), Null) => false,
        _ => true,
    }
}

/// `T` from the JSON it was written as, held to [`same_shape`]
fn read_strictly<T>(written: &serde_json::Value) -> Result<T, String>
where
    T: Serialize + serde::de::DeserializeOwned,
{
    let read: T =
        serde_json::from_value(written.clone()).map_err(|e| e.to_string())?;
    let again = serde_json::to_value(&read).map_err(|e| e.to_string())?;
    if same_shape(written, &again) {
        Ok(read)
    } else {
        Err("an array where an object belongs, or the reverse".into())
    }
}

/// 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.
///
/// Prefer this to deserializing [`GovernanceChainLink`]s directly, which
/// also accepts a link written as an array of its fields. Nothing serves
/// one; a verifier that would read it agrees with no other.
pub fn links_from_json(
    chain: &serde_json::Value,
) -> Result<Vec<GovernanceChainLink>, String> {
    chain
        .as_array()
        .ok_or("a chain is an array of links")?
        .iter()
        .map(read_strictly)
        .collect()
}

/// [`read_strictly`] for a field that is outside any signed `data`
fn read_as_written<'de, D, T>(deserializer: D) -> Result<Option<T>, D::Error>
where
    D: serde::Deserializer<'de>,
    T: Serialize + serde::de::DeserializeOwned,
{
    let written = serde_json::Value::deserialize(deserializer)?;
    if written.is_null() {
        return Ok(None);
    }
    read_strictly(&written)
        .map(Some)
        .map_err(serde::de::Error::custom)
}

/// The id series reserved for one entry type, if it has one. The other
/// types share `GOV-` and `APP-`, which the verifier does not tell apart.
fn reserved_prefix(
    entry_type: GovernanceLogEntryType,
) -> Option<GovernanceLogPrefix> {
    match entry_type {
        GovernanceLogEntryType::Amendment => Some(GovernanceLogPrefix::Amd),
        GovernanceLogEntryType::KeyRotation => Some(GovernanceLogPrefix::Key),
        GovernanceLogEntryType::StewardRecord => Some(GovernanceLogPrefix::Rec),
        GovernanceLogEntryType::Obligation => Some(GovernanceLogPrefix::Obl),
        GovernanceLogEntryType::DataSet => Some(GovernanceLogPrefix::Data),
        GovernanceLogEntryType::Test => Some(GovernanceLogPrefix::Test),
        GovernanceLogEntryType::CouncilDecision
        | GovernanceLogEntryType::AppealsCourtDecision
        | GovernanceLogEntryType::EmergencyAction
        | GovernanceLogEntryType::PolicyChange
        | GovernanceLogEntryType::StewardVeto
        | GovernanceLogEntryType::Unknown => None,
    }
}

/// The entry type a reserved id series belongs to, if it is reserved
fn reserved_for(prefix: GovernanceLogPrefix) -> Option<GovernanceLogEntryType> {
    match prefix {
        GovernanceLogPrefix::Amd => Some(GovernanceLogEntryType::Amendment),
        GovernanceLogPrefix::Key => Some(GovernanceLogEntryType::KeyRotation),
        GovernanceLogPrefix::Rec => Some(GovernanceLogEntryType::StewardRecord),
        GovernanceLogPrefix::Obl => Some(GovernanceLogEntryType::Obligation),
        GovernanceLogPrefix::Data => Some(GovernanceLogEntryType::DataSet),
        GovernanceLogPrefix::Test => Some(GovernanceLogEntryType::Test),
        GovernanceLogPrefix::Gov
        | GovernanceLogPrefix::App
        | GovernanceLogPrefix::Unknown => None,
    }
}

/// The id series an entry type must use, and must not
fn prefix_problem(link: &GovernanceChainLink) -> Option<String> {
    let prefix = link.id.prefix();
    match (reserved_prefix(link.entry_type), reserved_for(prefix)) {
        (Some(want), _) if prefix != want => Some(format!(
            "the id of a {} entry must be in the {want}- series, not {}",
            link.entry_type, link.id
        )),
        (None, Some(owner)) => Some(format!(
            "{prefix}- ids are reserved for {owner} entries, but {} is a {}",
            link.id, link.entry_type
        )),
        _ => None,
    }
}

/// 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
pub const OBLIGATION_FIXED: [&str; 5] = [
    "/until",
    "/owed_by",
    "/kind",
    "/source",
    "/agora_obligation",
];

/// 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
pub fn revision_touches<'a>(
    revision: &Revision,
    pointers: &[&'a str],
) -> Option<&'a str> {
    revision.patch.iter().find_map(|op| {
        let from = match op {
            json_patch::PatchOperation::Move(m) => Some(m.from.as_str()),
            json_patch::PatchOperation::Copy(c) => Some(c.from.as_str()),
            _ => None,
        };
        [Some(op.path().as_str()), from]
            .into_iter()
            .flatten()
            .find_map(|p| pointers.iter().copied().find(|f| overlaps(p, f)))
    })
}

/// Which earlier entry an amendment names, once it is known to be one
fn amendment_target(
    amendment: &Amendment,
    seq: u64,
    seq_of: &HashMap<&str, u64>,
    links: &[&GovernanceChainLink],
) -> Result<u64, AmendmentError> {
    amendment.validate()?;
    let target = *seq_of.get(amendment.target.as_str()).ok_or_else(|| {
        AmendmentError::UnknownTarget(amendment.target.clone())
    })?;
    if target >= seq {
        return Err(AmendmentError::ForwardReference(amendment.target.clone()));
    }
    let target_link = links[target as usize - 1];
    if target_link.attestation.entry_hash != amendment.target_entry_hash {
        return Err(AmendmentError::WrongTargetHash(amendment.target.clone()));
    }
    let on_obligation =
        target_link.entry_type == GovernanceLogEntryType::Obligation;
    if amendment.kind.is_obligation() && !on_obligation {
        return Err(AmendmentError::NotAnObligation {
            kind: amendment.kind,
            target: amendment.target.clone(),
        });
    }
    if on_obligation && kind_standing(amendment.kind).is_some() {
        return Err(AmendmentError::PrecedentialOnObligation(amendment.kind));
    }
    if on_obligation
        && let Some(revision) = &amendment.revision
        && let Some(path) = revision_touches(revision, &OBLIGATION_FIXED)
    {
        return Err(AmendmentError::FixedObligationField(path.to_string()));
    }
    Ok(target)
}

/// The key history as the walk discovers it
struct KeyWalk {
    /// Oldest first; the last entry is the active key
    history: Vec<(GovernanceKeyRecord, VerifyingKey)>,
    unanchored: Vec<PublicKeyHex>,
    /// Every key that has held the chain, voided ones included. The anchor
    /// lists retired and compromised keys too, so without this a thief
    /// could declare a "compromise" that rotates back to the key they stole.
    seen: HashSet<PublicKeyHex>,
    /// `chain_seq`s inside a compromise window
    repudiated: HashSet<u64>,
    genesis: PublicKeyHex,
    /// A rotation has carried the genesis key's certificate
    genesis_certified: bool,
}

impl KeyWalk {
    fn new(genesis: &VerifyingKey, anchor: &KeyAnchor) -> Self {
        let public_key = PublicKeyHex::from(genesis);
        Self {
            genesis: public_key,
            genesis_certified: false,
            history: vec![(
                GovernanceKeyRecord {
                    public_key,
                    from_seq: 1,
                    through_seq: None,
                    status: KeyStatus::Active,
                    introduced_by: None,
                    retired_by: None,
                    certified: false,
                },
                *genesis,
            )],
            unanchored: if anchor.contains(&public_key) {
                Vec::new()
            } else {
                vec![public_key]
            },
            seen: HashSet::from([public_key]),
            repudiated: HashSet::new(),
        }
    }

    /// The key that signs entry `seq`
    fn in_force(&self, seq: u64) -> (PublicKeyHex, VerifyingKey) {
        let (record, key) = self
            .history
            .iter()
            .rev()
            .find(|(r, _)| r.from_seq <= seq)
            .unwrap_or(&self.history[0]);
        (record.public_key, *key)
    }

    /// The key that signs whatever comes next
    fn active(&self) -> PublicKeyHex {
        self.history
            .last()
            .map(|(r, _)| r.public_key)
            .expect("the genesis key is always in the history")
    }

    fn close(
        &mut self,
        through_seq: u64,
        status: KeyStatus,
        by: &GovernanceLogId,
    ) {
        if let Some((record, _)) = self.history.last_mut() {
            record.through_seq = Some(through_seq);
            record.status = status;
            record.retired_by = Some(by.clone());
        }
    }

    fn open(
        &mut self,
        public_key: PublicKeyHex,
        key: VerifyingKey,
        from_seq: u64,
        by: &GovernanceLogId,
    ) {
        self.history.push((
            GovernanceKeyRecord {
                public_key,
                from_seq,
                through_seq: None,
                status: KeyStatus::Active,
                introduced_by: Some(by.clone()),
                retired_by: None,
                certified: true,
            },
            key,
        ));
    }

    /// Follow `rotation`, appended as `id` at `seq`
    fn apply(
        &mut self,
        rotation: &KeyRotation,
        link: &GovernanceChainLink,
        seq: u64,
        links: &[&GovernanceChainLink],
        roots: &RootSet,
    ) -> Result<(), RotationError> {
        rotation.verify_certified(seq, link.attestation.prev_hash, roots)?;
        let new_key = rotation
            .new_key
            .to_verifying_key()
            .map_err(|_| RotationError::BadNewKey)?;
        if self.seen.contains(&rotation.new_key) {
            return Err(RotationError::ReusedKey);
        }
        // The genesis key predates the root, so the first rotation brings
        // its certificate along. Whether that rotation is later voided by
        // a compromise does not matter: the certificate is the root's
        // statement, not the entry's.
        match (&rotation.outgoing_certificate, self.genesis_certified) {
            (None, false) => {
                return Err(RotationError::MissingGenesisCertificate);
            }
            (Some(_), true) => {
                return Err(RotationError::UnexpectedOutgoingCertificate);
            }
            (Some(certificate), false) => certificate
                .verify_for(&KeyCertStatement::genesis(self.genesis), roots)
                .map_err(RotationError::OutgoingCertificate)?,
            (None, true) => {}
        }
        match rotation.reason {
            RotationReason::Routine => {
                if rotation.old_key != self.in_force(seq).0 {
                    return Err(RotationError::WrongOldKey);
                }
                self.close(seq, KeyStatus::Retired, &link.id);
                self.open(rotation.new_key, new_key, seq + 1, &link.id);
            }
            RotationReason::Compromise => {
                let head = rotation
                    .last_trusted()
                    .ok_or(RotationError::MissingLastTrusted)?;
                let trusted_seq = head.chain_seq;
                let names_an_earlier_entry = trusted_seq >= 1
                    && trusted_seq < seq
                    && links[trusted_seq as usize - 1].id == head.id
                    && links[trusted_seq as usize - 1].attestation.entry_hash
                        == head.entry_hash;
                if !names_an_earlier_entry {
                    return Err(RotationError::UnknownLastTrusted);
                }
                // Trust cannot be anchored inside a window nobody trusts,
                // reattested or not: name an entry from before it.
                if self.repudiated.contains(&trusted_seq) {
                    return Err(RotationError::RepudiatedLastTrusted);
                }
                // The key in force at the last trusted entry: a rotation
                // inside the window is void with the rest of it.
                if rotation.old_key != self.in_force(trusted_seq).0 {
                    return Err(RotationError::WrongOldKey);
                }
                self.history.retain(|(r, _)| r.from_seq <= trusted_seq);
                self.close(trusted_seq, KeyStatus::Compromised, &link.id);
                self.open(rotation.new_key, new_key, seq, &link.id);
                self.repudiated.extend(trusted_seq + 1..seq);
            }
        }
        self.seen.insert(rotation.new_key);
        if !self.genesis_certified {
            self.genesis_certified = true;
            self.history[0].0.certified = true;
            self.unanchored.clear();
        }
        Ok(())
    }
}

/// Verify a whole chain from `genesis_key`, following the rotations that
/// `roots` certified and no others.
///
/// Links are sorted by `chain_seq` first, so the caller's order does not
/// matter. `retroactive` and `out_of_order` are recomputed from the
/// timestamps, not copied. `content_matches` is filled only for links that
/// carry `data` — for the rest, see
/// [`check_content`](GovernanceVerification::check_content).
///
/// `genesis_key` is the key the chain started under; it is not in the
/// chain, so a verifier has to be told. Until the chain's first rotation
/// certifies it, `anchor` is what vouches for it: if it is not there it
/// is reported in `unanchored_keys` rather than rejected — a client
/// pinning what it saw first passes `KeyAnchor::pinned(key)` and gets a
/// clean report. Pass [`RootSet::published`] for `roots` outside tests.
///
/// A rotation is authentic iff its [`KeyCertificate`] is valid for the
/// new key at that position; who signed the entry only follows from which
/// key *can* (the old one for a routine rotation, the new one once the
/// old is compromised). So a thief holding the online key can append
/// entries — which a compromise declaration then repudiates — but can
/// never move the chain.
///
/// The rules the report records that no type states on its own: an id
/// belongs to its entry type's series and appears once (`AMD-`, `KEY-`
/// and `REC-` are each reserved for one type); only an entry whose
/// own signature and linkage verify amends anything or moves the key, so
/// a forged entry cannot also describe the chain; and an amendment inside
/// a repudiated window has no effect unless a [`AmendmentKind::Reattested`]
/// vouches for its own entry first, resolved to a fixpoint.
pub fn verify_chain(
    links: &[GovernanceChainLink],
    genesis_key: &VerifyingKey,
    anchor: &KeyAnchor,
    roots: &RootSet,
) -> GovernanceVerification {
    let mut links: Vec<&GovernanceChainLink> = links.iter().collect();
    links.sort_by_key(|l| l.attestation.chain_seq);

    let mut seq_of: HashMap<&str, u64> = HashMap::new();
    let mut duplicates: HashSet<&str> = HashSet::new();
    for (i, link) in links.iter().enumerate() {
        if seq_of.insert(link.id.as_str(), i as u64 + 1).is_some() {
            duplicates.insert(link.id.as_str());
        }
    }

    let mut walk = KeyWalk::new(genesis_key, anchor);
    // (seq, amendment id, amendment, target seq), in chain order
    let mut amendments: Vec<(u64, GovernanceLogId, Amendment, u64)> =
        Vec::new();
    let mut entries: Vec<EntryVerdict> = Vec::with_capacity(links.len());
    let mut prev: Option<&GovernanceChainLink> = None;

    for (i, link) in links.iter().enumerate() {
        let a = &link.attestation;
        let expected_seq = i as u64 + 1;
        let mut problems: Vec<String> = Vec::new();

        if let Some(problem) = prefix_problem(link) {
            problems.push(problem);
        }
        if duplicates.contains(link.id.as_str()) {
            problems.push(format!("{} appears more than once", link.id));
        }

        // The two entry types the verifier has to read. `data` is hashed
        // against the envelope before it is parsed, so what is read is
        // what was signed.
        let carries_meaning = matches!(
            link.entry_type,
            GovernanceLogEntryType::Amendment
                | GovernanceLogEntryType::KeyRotation
        );
        let mut amendment: Option<Amendment> = None;
        let mut rotation: Option<KeyRotation> = None;
        let mut content_matches: Option<bool> = None;
        match &link.data {
            Some(data) if non_integer_number(data).is_some() => {
                content_matches = Some(false);
                problems.push(format!(
                    "`data` has a number that is not a 64-bit integer at {:?}; \
                     governance data never contains one",
                    non_integer_number(data).unwrap_or_default()
                ));
            }
            Some(data) => {
                let matched = data_hash(data) == a.data_hash;
                content_matches = Some(matched);
                if !matched {
                    if carries_meaning {
                        problems.push(
                            "`data` does not hash to the attested data_hash"
                                .into(),
                        );
                    }
                } else {
                    match link.entry_type {
                        GovernanceLogEntryType::Amendment => {
                            match read_strictly(data) {
                                Ok(v) => amendment = Some(v),
                                Err(e) => problems.push(format!(
                                    "amendment `data` is malformed: {e}"
                                )),
                            }
                        }
                        GovernanceLogEntryType::KeyRotation => {
                            match read_strictly(data) {
                                Ok(v) => rotation = Some(v),
                                Err(e) => problems.push(format!(
                                    "key_rotation `data` is malformed: {e}"
                                )),
                            }
                        }
                        _ => {}
                    }
                }
            }
            None if carries_meaning => problems.push(format!(
                "a {} entry must carry its `data`",
                link.entry_type
            )),
            None => {}
        }

        // A compromise declaration is signed by the new key, and is
        // taken at its word only if the root certified that key here.
        // Everything else is signed by the key in force.
        let declared = rotation
            .as_ref()
            .filter(|r| r.reason == RotationReason::Compromise)
            .map(|r| {
                if walk.seen.contains(&r.new_key) {
                    return Err(RotationError::ReusedKey);
                }
                r.verify_certified(expected_seq, a.prev_hash, roots)?;
                r.new_key
                    .to_verifying_key()
                    .map_err(|_| RotationError::BadNewKey)
            });
        let (key_hex, key) = match &declared {
            Some(Ok(k)) => (PublicKeyHex::from(k), *k),
            _ => walk.in_force(expected_seq),
        };
        // Say why a declaration was not taken at its word; the bad
        // signature that follows is the consequence, not the cause.
        if let Some(Err(e)) = &declared {
            problems.push(e.to_string());
        }

        let (hash_ok, signature_valid) = match verify_link(link, &key) {
            Ok(()) => (true, true),
            Err(LinkError::BadSignature) => {
                problems.push(LinkError::BadSignature.to_string());
                (true, false)
            }
            Err(e) => {
                problems.push(e.to_string());
                (false, false)
            }
        };

        let mut link_valid = hash_ok;
        if a.chain_seq != expected_seq {
            link_valid = false;
            problems.push(format!(
                "chain_seq {} where {expected_seq} was expected",
                a.chain_seq
            ));
        }
        let expected_prev = prev.map(|p| p.attestation.entry_hash);
        if a.prev_hash != expected_prev {
            link_valid = false;
            problems.push(match (a.prev_hash, expected_prev) {
                (Some(_), None) => "first entry names a predecessor".into(),
                (None, Some(_)) => "prev_hash is null mid-chain".into(),
                _ => "prev_hash is not the previous entry's entry_hash".into(),
            });
        }
        let out_of_order = prev.is_some_and(|p| link.created_at < p.created_at);

        // Only an entry that is itself authentic moves the key or amends
        // anything: a forged one already fails the chain, and must not
        // also get to describe it.
        let authentic = signature_valid && link_valid;
        if let Some(rotation) = rotation.as_ref().filter(|_| authentic)
            && let Err(e) =
                walk.apply(rotation, link, expected_seq, &links, roots)
        {
            let problem = e.to_string();
            if !problems.contains(&problem) {
                problems.push(problem);
            }
        }
        // Texts are checked against what the entry signed whether or not
        // the amendment takes effect: a substituted text is a lie about
        // the record either way.
        let mut texts = None;
        if let Some(amendment) = amendment
            .as_ref()
            .filter(|a| authentic && a.validate().is_ok())
        {
            match amendment.text_status(link.texts.as_ref()) {
                Ok(status) => texts = status,
                Err(e) => problems.push(e.to_string()),
            }
        } else if link.texts.as_ref().is_some_and(|t| !t.is_empty()) {
            problems.push(AmendmentError::UncommittedText.to_string());
        }
        if let Some(amendment) = amendment.filter(|_| authentic) {
            match amendment_target(&amendment, expected_seq, &seq_of, &links) {
                Ok(target) => amendments.push((
                    expected_seq,
                    link.id.clone(),
                    amendment,
                    target,
                )),
                Err(e) => problems.push(e.to_string()),
            }
        }

        entries.push(EntryVerdict {
            id: link.id.clone(),
            chain_seq: a.chain_seq,
            signature_valid,
            link_valid,
            content_matches,
            retroactive: is_retroactive(link.created_at, a.signed_at),
            out_of_order,
            amended_by: Vec::new(),
            signed_by: Some(key_hex),
            redacted: false,
            redacted_data_hash: None,
            revisions: Vec::new(),
            latest_data_hash: None,
            superseded_revisions: Vec::new(),
            history: RevisionHistory::default(),
            repudiated: false,
            reattested_by: Vec::new(),
            texts,
            problem: (!problems.is_empty()).then(|| problems.join("; ")),
        });
        prev = Some(link);
    }

    // Reattestations first, and to a fixpoint: an amendment inside a
    // repudiated window has no effect unless something later vouches for
    // it, and that something can be another reattestation.
    let mut applied = vec![false; amendments.len()];
    loop {
        let mut changed = false;
        for (i, (seq, id, amendment, target)) in amendments.iter().enumerate() {
            if applied[i]
                || amendment.kind != AmendmentKind::Reattested
                || walk.repudiated.contains(seq)
            {
                continue;
            }
            applied[i] = true;
            entries[*target as usize - 1].reattested_by.push(id.clone());
            walk.repudiated.remove(target);
            changed = true;
        }
        if !changed {
            break;
        }
    }

    for (seq, id, amendment, target) in &amendments {
        if walk.repudiated.contains(seq) {
            continue;
        }
        let entry = &mut entries[*target as usize - 1];
        entry.amended_by.push(id.clone());
        let mut unrebased = false;
        if let Some(redaction) = &amendment.redaction {
            // A redaction of a revised entry says what the rebase gives,
            // or the rebased history is checked against nothing.
            unrebased = !entry.revisions.is_empty()
                && redaction.resulting_latest_hash.is_none();
            entry.redacted = true;
            entry.redacted_data_hash = Some(redaction.resulting_data_hash);
            // The revisions so far are rebased over the redacted data.
            entry.history.rebased = entry.history.revisions.len();
            entry.history.rebased_hash = redaction.resulting_latest_hash;
            entry.latest_data_hash = redaction.resulting_latest_hash;
            entry.superseded_revisions = entry.revisions.clone();
        }
        if let Some(revision) = &amendment.revision {
            entry.revisions.push(id.clone());
            entry.latest_data_hash = Some(revision.resulting_data_hash);
            entry.history.revisions.push((id.clone(), revision.clone()));
        }
        if unrebased {
            let target = entry.id.clone();
            add_problem(
                &mut entries[*seq as usize - 1].problem,
                format!(
                    "the redaction of {target}, which has revisions, names no \
                     resulting_latest_hash"
                ),
            );
        }
    }

    // A redacted entry's content is what the redaction left behind, and a
    // revised one's revisions are checked against it.
    for (i, link) in links.iter().enumerate() {
        let entry = &mut entries[i];
        if let Some(data) = &link.data
            && entry.content_matches.is_some()
            && (entry.redacted || !entry.history.revisions.is_empty())
        {
            entry.content_matches =
                Some(entry.content_check(link.attestation.data_hash, data));
        }
    }

    let mut seen = HashSet::new();
    walk.unanchored.retain(|key| seen.insert(*key));

    let mut repudiated = Vec::new();
    for (i, entry) in entries.iter_mut().enumerate() {
        if walk.repudiated.contains(&(i as u64 + 1)) {
            entry.repudiated = true;
            repudiated.push(entry.id.clone());
        }
    }

    GovernanceVerification {
        public_key: walk.active(),
        ok: false,
        head: prev.map(|p| p.id.clone()),
        entries,
        keys: walk.history.into_iter().map(|(record, _)| record).collect(),
        unanchored_keys: walk.unanchored,
        repudiated,
    }
    .settle()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn pointer_tokens_escape_and_unescape() {
        assert_eq!(escape_pointer_token("a/b~c"), "a~1b~0c");
        // `~01` is an escaped `~1`, not an escaped `/`
        assert_eq!(unescape_pointer_token("~01"), "~1");
        for token in ["", "plain", "a/b", "~", "~1", "/~0/"] {
            assert_eq!(
                unescape_pointer_token(&escape_pointer_token(token)),
                token
            );
        }
        assert_eq!(
            pointer_tokens("/rounds/0/a~1b~0c"),
            ["rounds", "0", "a/b~c"]
        );
        assert!(pointer_tokens("").is_empty());
    }

    /// Each kind of record names what it cites in its own field; an entry
    /// type that cites nothing names nothing, and a malformed field is an
    /// error.
    #[test]
    fn citations_are_read_from_each_records_own_field() {
        use serde_json::json;
        let id = |s: &str| s.parse::<GovernanceLogId>().unwrap();
        assert_eq!(
            citations_in(
                GovernanceLogEntryType::StewardRecord,
                &json!({"title": "t", "concerns": ["GOV-2026-0011", "AMD-2026-0004"]}),
            )
            .unwrap(),
            vec![
                (id("GOV-2026-0011"), CitationRelation::Concerns),
                (id("AMD-2026-0004"), CitationRelation::Concerns),
            ]
        );
        assert_eq!(
            citations_in(
                GovernanceLogEntryType::Amendment,
                &json!({"target": "APP-2026-0001", "authority": "GOV-2026-0005"}),
            )
            .unwrap(),
            vec![(id("GOV-2026-0005"), CitationRelation::Authority)],
            "the target is not a citation: it is listed under `amendments`"
        );
        assert_eq!(
            citations_in(
                GovernanceLogEntryType::CouncilDecision,
                &json!({"overrules": ["APP-2026-0002"]}),
            )
            .unwrap(),
            vec![(id("APP-2026-0002"), CitationRelation::Overrules)]
        );
        assert!(
            citations_in(
                GovernanceLogEntryType::Amendment,
                &json!({"authority": null})
            )
            .unwrap()
            .is_empty()
        );
        // A malformed field is an error that says which relation it was,
        // never a silent "cites nothing"
        assert!(matches!(
            citations_in(
                GovernanceLogEntryType::StewardRecord,
                &json!({"concerns": "GOV-2026-0011"})
            ),
            Err(MalformedCitation {
                relation: CitationRelation::Concerns,
                ..
            })
        ));
        assert!(
            citations_in(
                GovernanceLogEntryType::AppealsCourtDecision,
                &json!({"concerns": ["GOV-2026-0011"]}),
            )
            .unwrap()
            .is_empty()
        );
    }
    use crate::crypto::generate_keypair;
    use serde_json::json;

    pub(super) fn gov(n: u32) -> GovernanceLogId {
        format!("GOV-2026-{n:04}").parse().unwrap()
    }

    pub(super) fn amd(n: u32) -> GovernanceLogId {
        format!("AMD-2026-{n:04}").parse().unwrap()
    }

    pub(super) fn key_id(n: u32) -> GovernanceLogId {
        format!("KEY-2026-{n:04}").parse().unwrap()
    }

    pub(super) fn rec(n: u32) -> GovernanceLogId {
        format!("REC-2026-{n:04}").parse().unwrap()
    }

    pub(super) fn obl(n: u32) -> GovernanceLogId {
        format!("OBL-2026-{n:04}").parse().unwrap()
    }

    pub(super) fn data_id(n: u32) -> GovernanceLogId {
        format!("DATA-2026-{n:04}").parse().unwrap()
    }

    pub(super) fn test_id(n: u32) -> GovernanceLogId {
        format!("TEST-2026-{n:04}").parse().unwrap()
    }

    pub(super) fn at(secs: i64) -> DateTime<Utc> {
        DateTime::from_timestamp(1_700_000_000 + secs, 123_456_789).unwrap()
    }

    /// The anchor a client that pinned the key it first saw would hold
    fn anchored(key: &VerifyingKey) -> KeyAnchor {
        KeyAnchor::pinned(key.into())
    }

    /// `draft` under salts fixed by its texts and `seq`, so that a chain
    /// built twice is the same bytes twice
    pub(super) fn resalted(draft: &AmendmentDraft, seq: u64) -> AmendmentDraft {
        let fix = |field: &str, t: &Option<CommittedText>| {
            t.as_ref().map(|t| {
                let salt = Sha256::digest(format!("{seq}/{field}/{}", t.text));
                CommittedText::with_salt(
                    TextSalt::from(<[u8; 32]>::from(salt)),
                    t.text.clone(),
                )
            })
        };
        let texts = AmendmentTexts {
            basis: fix("basis", &draft.texts.basis),
            note: fix("note", &draft.texts.note),
            rationale: fix("rationale", &draft.texts.rationale),
        };
        let commit = |t: &Option<CommittedText>| {
            t.as_ref().map(|t| AmendmentText::Committed(t.commitment()))
        };
        AmendmentDraft {
            amendment: Amendment {
                basis: commit(&texts.basis).unwrap(),
                note: commit(&texts.note).unwrap(),
                rationale: commit(&texts.rationale),
                ..draft.amendment.clone()
            },
            texts,
        }
    }

    /// `draft` as version 1 wrote it: the texts in the signed `data`
    pub(super) fn v1(draft: AmendmentDraft) -> Amendment {
        let plain =
            |t: Option<CommittedText>| t.map(|t| AmendmentText::Plain(t.text));
        Amendment {
            agora_governance_amendment: 1,
            basis: plain(draft.texts.basis).unwrap(),
            note: plain(draft.texts.note).unwrap(),
            rationale: plain(draft.texts.rationale),
            ..draft.amendment
        }
    }

    /// A throwaway root key. Fixed, so the vectors are byte-stable; the
    /// real ones live on hardware and sign nothing in a test.
    pub(super) fn root(n: u8) -> SigningKey {
        SigningKey::from_bytes(&[0xA0 + n; 32])
    }

    /// `root(1)` and `root(2)`, either of which suffices
    pub(super) fn roots() -> RootSet {
        RootSet::new(
            [1, 2].map(|n| PublicKeyHex::from(&root(n).verifying_key())),
            1,
        )
    }

    /// `statement`, signed by each of `signers` as a root would
    pub(super) fn certify(
        signers: &[&SigningKey],
        statement: KeyCertStatement,
    ) -> KeyCertificate {
        use ed25519_dalek::Signer;
        let message = statement.signed_bytes();
        signers.iter().fold(
            KeyCertificate::unsigned(statement),
            |certificate, signer| {
                certificate.with(RootSignature {
                    root_key: (&signer.verifying_key()).into(),
                    signature: signer.sign(&message).into(),
                })
            },
        )
    }

    /// `root(1)`'s routine certificate for `key` at `c`'s next position
    fn for_new_at(c: &Chain, key: &VerifyingKey) -> KeyCertificate {
        certify(
            &[&root(1)],
            KeyCertStatement::routine(key.into(), c.next_seq(), c.prev_hash()),
        )
    }

    pub(super) fn link(
        key: &SigningKey,
        n: u32,
        prev: Option<&GovernanceChainLink>,
        data: &serde_json::Value,
        signed_at: DateTime<Utc>,
    ) -> GovernanceChainLink {
        let created_at = truncate_to_micros(at(n as i64 * 10));
        let envelope = Envelope::new(
            gov(n),
            GovernanceLogEntryType::CouncilDecision,
            created_at,
            prev.map(|p| p.attestation.entry_hash),
            data_hash(data),
        );
        let attestation = attest(
            key,
            &envelope,
            prev.map_or(1, |p| p.attestation.chain_seq + 1),
            signed_at,
        );
        GovernanceChainLink {
            id: gov(n),
            entry_type: GovernanceLogEntryType::CouncilDecision,
            created_at,
            attestation,
            data: None,
            texts: None,
        }
    }

    pub(super) fn chain(key: &SigningKey, n: u32) -> Vec<GovernanceChainLink> {
        let mut out: Vec<GovernanceChainLink> = Vec::new();
        for i in 1..=n {
            let data = json!({"title": format!("Decision {i}"), "outcome": "approved"});
            let l = link(key, i, out.last(), &data, at(i as i64 * 10 + 1));
            out.push(l);
        }
        out
    }

    /// A chain under construction: one entry per `push`, each series
    /// numbered on its own, `data` carried for the entries a verifier
    /// reads.
    pub(super) struct Chain {
        pub(super) links: Vec<GovernanceChainLink>,
        gov: u32,
        amd: u32,
        key: u32,
        /// Whoever signed the first entry
        genesis: Option<PublicKeyHex>,
    }

    impl Chain {
        pub(super) fn new() -> Self {
            Self {
                links: Vec::new(),
                gov: 0,
                amd: 0,
                key: 0,
                genesis: None,
            }
        }

        pub(super) fn prev_hash(&self) -> Option<Sha256Hex> {
            self.links.last().map(|l| l.attestation.entry_hash)
        }

        /// The `entry_hash` of the 1-indexed link `seq`
        pub(super) fn hash_at(&self, seq: usize) -> Sha256Hex {
            self.links[seq - 1].attestation.entry_hash
        }

        /// The `chain_seq` the next entry gets
        pub(super) fn next_seq(&self) -> u64 {
            self.links.len() as u64 + 1
        }

        /// The 1-indexed link `seq`, as a compromise names it
        pub(super) fn head(&self, seq: usize) -> TrustedHead {
            TrustedHead {
                id: self.links[seq - 1].id.clone(),
                chain_seq: seq as u64,
                entry_hash: self.hash_at(seq),
            }
        }

        /// The genesis certificate, if the next rotation is the first
        fn outgoing(&self, rotation: KeyRotation) -> KeyRotation {
            match (self.key, self.genesis) {
                (0, Some(genesis)) => rotation.with_outgoing(certify(
                    &[&root(1)],
                    KeyCertStatement::genesis(genesis),
                )),
                _ => rotation,
            }
        }

        /// A routine rotation to `new` at the next position, certified by
        /// `root(1)`
        pub(super) fn routine(
            &self,
            old: &VerifyingKey,
            new: &SigningKey,
        ) -> KeyRotation {
            let statement = KeyCertStatement::routine(
                (&new.verifying_key()).into(),
                self.next_seq(),
                self.prev_hash(),
            );
            self.outgoing(KeyRotation::routine(
                old.into(),
                new,
                self.prev_hash(),
                at(self.next_seq() as i64 * 10 + 5),
                certify(&[&root(1)], statement),
            ))
        }

        /// A compromise declaration at the next position trusting `old`
        /// through the 1-indexed link `trusted`, certified by `root(1)`
        pub(super) fn compromise(
            &self,
            old: &VerifyingKey,
            new: &SigningKey,
            trusted: usize,
        ) -> KeyRotation {
            let statement = KeyCertStatement::compromise(
                (&new.verifying_key()).into(),
                self.next_seq(),
                self.prev_hash(),
                self.head(trusted),
            );
            self.outgoing(KeyRotation::compromise(
                old.into(),
                new,
                self.prev_hash(),
                at(self.next_seq() as i64 * 10 + 5),
                certify(&[&root(1)], statement),
            ))
        }

        /// What [`Chain::amend`] will call the next amendment
        pub(super) fn next_amd(&self) -> GovernanceLogId {
            amd(self.amd + 1)
        }

        pub(super) fn push(
            &mut self,
            signer: &SigningKey,
            id: GovernanceLogId,
            entry_type: GovernanceLogEntryType,
            data: serde_json::Value,
            carry: bool,
        ) -> GovernanceLogId {
            self.genesis
                .get_or_insert_with(|| (&signer.verifying_key()).into());
            let n = self.links.len() as i64 + 1;
            let created_at = truncate_to_micros(at(n * 10));
            let envelope = Envelope::new(
                id.clone(),
                entry_type,
                created_at,
                self.prev_hash(),
                data_hash(&data),
            );
            let attestation =
                attest(signer, &envelope, n as u64, at(n * 10 + 1));
            self.links.push(GovernanceChainLink {
                id: id.clone(),
                entry_type,
                created_at,
                attestation,
                data: carry.then_some(data),
                texts: None,
            });
            id
        }

        /// A council decision carrying `data` (which the link does not,
        /// as the chain endpoint does not carry transcripts)
        pub(super) fn entry(
            &mut self,
            signer: &SigningKey,
            data: serde_json::Value,
        ) -> GovernanceLogId {
            self.gov += 1;
            let id = gov(self.gov);
            self.push(
                signer,
                id,
                GovernanceLogEntryType::CouncilDecision,
                data,
                false,
            )
        }

        pub(super) fn decision(
            &mut self,
            signer: &SigningKey,
        ) -> GovernanceLogId {
            let data = json!({"title": format!("Decision {}", self.gov + 1)});
            self.entry(signer, data)
        }

        /// `draft`'s amendment as the entry's `data`, its texts beside it
        pub(super) fn amend(
            &mut self,
            signer: &SigningKey,
            draft: &AmendmentDraft,
        ) -> GovernanceLogId {
            let draft = resalted(draft, self.next_seq());
            let id = self.amend_v1(signer, &draft.amendment);
            let link = self.links.last_mut().unwrap();
            link.texts = Some(draft.texts);
            id
        }

        /// An amendment with nothing beside it: version 1, or a version 2
        /// whose texts have all been withheld
        pub(super) fn amend_v1(
            &mut self,
            signer: &SigningKey,
            amendment: &Amendment,
        ) -> GovernanceLogId {
            self.amd += 1;
            let id = amd(self.amd);
            self.push(
                signer,
                id,
                GovernanceLogEntryType::Amendment,
                serde_json::to_value(amendment).unwrap(),
                true,
            )
        }

        pub(super) fn rotate(
            &mut self,
            signer: &SigningKey,
            rotation: &KeyRotation,
        ) -> GovernanceLogId {
            self.key += 1;
            let id = key_id(self.key);
            self.push(
                signer,
                id,
                GovernanceLogEntryType::KeyRotation,
                serde_json::to_value(rotation).unwrap(),
                true,
            )
        }
    }

    // -- canonical JSON --

    #[test]
    fn canonical_json_sorts_keys_at_every_level() {
        let v = json!({"b": {"z": 1, "a": [{"y": 2, "x": 3}]}, "a": null});
        assert_eq!(
            canonical_json(&v),
            br#"{"a":null,"b":{"a":[{"x":3,"y":2}],"z":1}}"#
        );
    }

    #[test]
    fn canonical_json_is_compact_and_escapes_like_serde() {
        let v = json!({"s": "tab\there \"q\" ünïcode \u{1F600}", "n": [1, -2, 3.5, true, false]});
        let bytes = canonical_json(&v);
        let text = std::str::from_utf8(&bytes).unwrap();
        assert_eq!(
            text,
            r#"{"n":[1,-2,3.5,true,false],"s":"tab\there \"q\" ünïcode 😀"}"#
        );
    }

    #[test]
    fn canonical_json_ignores_insertion_order() {
        let mut a = serde_json::Map::new();
        a.insert("z".into(), json!(1));
        a.insert("a".into(), json!(2));
        let mut b = serde_json::Map::new();
        b.insert("a".into(), json!(2));
        b.insert("z".into(), json!(1));
        assert_eq!(
            canonical_json(&serde_json::Value::Object(a)),
            canonical_json(&serde_json::Value::Object(b))
        );
    }

    #[test]
    fn canonical_json_empty_containers() {
        assert_eq!(canonical_json(&json!({})), b"{}");
        assert_eq!(canonical_json(&json!([])), b"[]");
        assert_eq!(
            canonical_json(&json!({"a": {}, "b": []})),
            br#"{"a":{},"b":[]}"#
        );
    }

    // -- envelope --

    #[test]
    fn preimage_is_declaration_ordered_json() {
        let e = Envelope::new(
            gov(1),
            GovernanceLogEntryType::AppealsCourtDecision,
            at(0),
            None,
            data_hash(&json!({})),
        );
        let text = String::from_utf8(e.preimage()).unwrap();
        assert!(text.starts_with(r#"{"agora_governance_log":1,"id":"GOV-2026-0001","entry_type":"appeals_court_decision","created_at":1700000000123456,"prev_hash":null,"data_hash":""#), "{text}");
    }

    #[test]
    fn every_envelope_field_changes_the_hash() {
        let base = Envelope::new(
            gov(1),
            GovernanceLogEntryType::CouncilDecision,
            at(0),
            None,
            data_hash(&json!({"a":1})),
        );
        let h = base.entry_hash();
        let mut e = base.clone();
        e.id = gov(2);
        assert_ne!(e.entry_hash(), h);
        let mut e = base.clone();
        e.entry_type = GovernanceLogEntryType::PolicyChange;
        assert_ne!(e.entry_hash(), h);
        let mut e = base.clone();
        e.created_at += 1;
        assert_ne!(e.entry_hash(), h);
        let mut e = base.clone();
        e.prev_hash = Some(h);
        assert_ne!(e.entry_hash(), h);
        let mut e = base.clone();
        e.data_hash = data_hash(&json!({"a":2}));
        assert_ne!(e.entry_hash(), h);
        assert_eq!(base.entry_hash(), h, "and it is deterministic");
    }

    #[test]
    fn truncation_matches_what_the_envelope_carries() {
        let t = at(0);
        assert_eq!(truncate_to_micros(t).timestamp_subsec_nanos(), 123_456_000);
        assert_eq!(truncate_to_seconds(t).timestamp_subsec_nanos(), 0);
        assert_eq!(
            Envelope::new(
                gov(1),
                GovernanceLogEntryType::CouncilDecision,
                t,
                None,
                data_hash(&json!(null))
            )
            .created_at,
            truncate_to_micros(t).timestamp_micros()
        );
    }

    // -- hex newtypes --

    #[test]
    fn hex_newtypes_round_trip_and_reject_wrong_lengths() {
        let h = data_hash(&json!(1));
        let s = serde_json::to_string(&h).unwrap();
        assert_eq!(s.len(), 66);
        let back: Sha256Hex = serde_json::from_str(&s).unwrap();
        assert_eq!(back, h);
        assert!(serde_json::from_str::<Sha256Hex>("\"abcd\"").is_err());
        assert!("zz".repeat(32).parse::<Sha256Hex>().is_err());
        assert!(Sha256Hex::try_from(vec![0u8; 31]).is_err());
        assert_eq!(format!("{h:?}"), format!("Sha256Hex({h})"));
    }

    // -- signing and verification --

    #[test]
    fn attest_then_verify_link() {
        let (key, pk) = generate_keypair();
        let l = link(&key, 1, None, &json!({"a": 1}), at(5));
        assert_eq!(verify_link(&l, &pk), Ok(()));
        assert!(verify_data(&l, &json!({"a": 1})));
        assert!(!verify_data(&l, &json!({"a": 2})));
        assert!(!l.attestation.retroactive);
    }

    #[test]
    fn wrong_key_fails_signature_only() {
        let (key, _) = generate_keypair();
        let (_, other) = generate_keypair();
        let l = link(&key, 1, None, &json!({}), at(5));
        assert_eq!(verify_link(&l, &other), Err(LinkError::BadSignature));
    }

    #[test]
    fn tampering_with_any_attested_field_is_detected() {
        let (key, pk) = generate_keypair();
        let l = link(&key, 1, None, &json!({"a": 1}), at(5));

        let mut t = l.clone();
        t.created_at += chrono::Duration::microseconds(1);
        assert_eq!(verify_link(&t, &pk), Err(LinkError::HashMismatch));

        let mut t = l.clone();
        t.entry_type = GovernanceLogEntryType::StewardVeto;
        assert_eq!(verify_link(&t, &pk), Err(LinkError::HashMismatch));

        let mut t = l.clone();
        t.attestation.data_hash = data_hash(&json!({"a": 2}));
        assert_eq!(verify_link(&t, &pk), Err(LinkError::HashMismatch));

        // Back-dating the signature: the hash still recomputes, but the
        // signature covered the real signed_at.
        let mut t = l.clone();
        t.attestation.signed_at -= chrono::Duration::seconds(1);
        assert_eq!(verify_link(&t, &pk), Err(LinkError::BadSignature));

        let mut t = l.clone();
        t.attestation.envelope_version = 2;
        assert_eq!(verify_link(&t, &pk), Err(LinkError::UnsupportedVersion(2)));
    }

    #[test]
    fn a_good_chain_verifies_in_any_input_order() {
        let (key, pk) = generate_keypair();
        let mut c = chain(&key, 4);
        c.reverse();
        let v = verify_chain(&c, &pk, &anchored(&pk), &roots());
        assert!(v.ok, "{v:#?}");
        assert_eq!(v.head, Some(gov(4)));
        assert_eq!(
            v.entries.iter().map(|e| e.chain_seq).collect::<Vec<_>>(),
            [1, 2, 3, 4]
        );
        assert!(v.entries.iter().all(|e| e.content_matches.is_none()
            && e.problem.is_none()
            && !e.out_of_order));
        assert_eq!(v.public_key, PublicKeyHex::from(&pk));
    }

    #[test]
    fn empty_chain_is_ok_with_no_head() {
        let (_, pk) = generate_keypair();
        let v = verify_chain(&[], &pk, &anchored(&pk), &roots());
        assert!(v.ok);
        assert!(v.head.is_none());
        assert!(v.entries.is_empty());
    }

    #[test]
    fn a_changed_entry_breaks_its_signature_and_the_next_link() {
        let (key, pk) = generate_keypair();
        let mut c = chain(&key, 3);
        // Re-attest entry 2 with different data but the same predecessor,
        // as a key holder rewriting history would.
        let rewritten = link(
            &key,
            2,
            Some(&c[0]),
            &json!({"title": "Decision 2", "outcome": "REJECTED"}),
            at(21),
        );
        c[1] = rewritten;
        let v = verify_chain(&c, &pk, &anchored(&pk), &roots());
        assert!(!v.ok);
        assert!(
            v.entries[1].signature_valid && v.entries[1].link_valid,
            "the rewrite itself is well-formed: {:#?}",
            v.entries[1]
        );
        assert!(
            !v.entries[2].link_valid,
            "but entry 3 no longer points at it: {:#?}",
            v.entries[2]
        );
        assert!(
            v.entries[2]
                .problem
                .as_deref()
                .unwrap()
                .contains("prev_hash")
        );
    }

    #[test]
    fn a_removed_entry_is_a_gap_and_a_broken_link() {
        let (key, pk) = generate_keypair();
        let mut c = chain(&key, 3);
        c.remove(1);
        let v = verify_chain(&c, &pk, &anchored(&pk), &roots());
        assert!(!v.ok);
        assert!(v.entries[0].link_valid);
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(p.contains("chain_seq 3 where 2 was expected"), "{p}");
        assert!(p.contains("prev_hash"), "{p}");
    }

    /// `verify_governance_log`'s default: counts, the failures by id and
    /// the first in full, never one row per entry (beta round, 2026-10-15)
    #[test]
    fn a_summary_counts_and_names_the_failures() {
        let (key, pk) = generate_keypair();
        let clean =
            verify_chain(&chain(&key, 3), &pk, &anchored(&pk), &roots());
        let summary = clean.summary();
        assert!(summary.ok);
        assert_eq!((summary.entries, summary.failed.len()), (3, 0));
        assert_eq!(summary.head, clean.head);
        assert!(summary.first_failure.is_none());
        assert!(summary.how_to_read.contains("full=true"));

        let mut c = chain(&key, 3);
        c.remove(1);
        let v = verify_chain(&c, &pk, &anchored(&pk), &roots());
        let summary = v.summary();
        assert!(!summary.ok);
        assert_eq!(summary.link_failures, 1);
        assert_eq!(summary.failed, vec![v.entries[1].id.clone()]);
        assert_eq!(summary.first_failure.as_ref(), Some(&v.entries[1]));
        let json = serde_json::to_value(&summary).unwrap();
        assert!(json["entries"].is_u64(), "a count, not the rows: {json}");
    }

    #[test]
    fn a_second_genesis_is_rejected() {
        let (key, pk) = generate_keypair();
        let mut c = chain(&key, 2);
        let rogue = link(&key, 2, None, &json!({}), at(21));
        c[1] = rogue;
        let v = verify_chain(&c, &pk, &anchored(&pk), &roots());
        assert!(!v.ok);
        assert!(
            v.entries[1]
                .problem
                .as_deref()
                .unwrap()
                .contains("null mid-chain")
        );
    }

    #[test]
    fn retroactive_and_out_of_order_are_recomputed_not_copied() {
        let (key, pk) = generate_keypair();
        let first = link(&key, 1, None, &json!({}), at(10 + 3600));
        // Second entry recorded *before* the first by the clock, but after it
        // in the chain. Valid chain, flagged order.
        let created = truncate_to_micros(at(5));
        let envelope = Envelope::new(
            gov(2),
            GovernanceLogEntryType::CouncilDecision,
            created,
            Some(first.attestation.entry_hash),
            data_hash(&json!({})),
        );
        let attestation = attest(&key, &envelope, 2, at(6));
        let mut second = GovernanceChainLink {
            id: gov(2),
            entry_type: GovernanceLogEntryType::CouncilDecision,
            created_at: created,
            attestation,
            data: None,
            texts: None,
        };
        second.attestation.retroactive = true; // a lying flag on the wire
        let v = verify_chain(&[first, second], &pk, &anchored(&pk), &roots());
        assert!(v.ok, "{v:#?}");
        assert!(v.entries[0].retroactive);
        assert!(!v.entries[1].retroactive, "recomputed from timestamps");
        assert!(v.entries[1].out_of_order);
    }

    #[test]
    fn content_mismatch_settles_to_not_ok() {
        let (key, pk) = generate_keypair();
        let c = chain(&key, 1);
        let mut v = verify_chain(&c, &pk, &anchored(&pk), &roots());
        v.entries[0].content_matches = Some(true);
        assert!(v.clone().settle().ok);
        v.entries[0].content_matches = Some(false);
        assert!(!v.settle().ok);
    }

    // -- amendments --

    #[test]
    fn an_amendment_fills_amended_by_on_its_target() {
        let (key, pk) = generate_keypair();
        let mut c = Chain::new();
        let target = c.decision(&key);
        c.decision(&key);
        let amendment = AmendmentDraft::new(
            target,
            c.hash_at(1),
            AmendmentKind::NonPrecedential,
            "§1 (Red Team Cases Recharacterized)",
            "diagnostic finding — not citable as moderation precedent",
        )
        .unwrap()
        .with_authority(gov(5))
        .with_rationale("§5 leaves the ruling itself standing");
        let id = c.amend(&key, &amendment);

        let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(v.ok, "{v:#?}");
        assert_eq!(v.entries[0].amended_by, vec![id]);
        assert!(v.entries[1].amended_by.is_empty());
        assert!(!v.entries[0].redacted);
        assert_eq!(v.head, Some(amd(1)));
        // The amendment link carries `data`, so its own content is checked.
        assert_eq!(v.entries[2].content_matches, Some(true));
        assert_eq!(v.entries[0].content_matches, None);
        assert_eq!(
            standing([amendment.amendment.kind]),
            Standing::NonPrecedential
        );
    }

    #[test]
    fn an_amendment_must_name_an_earlier_entry_by_its_exact_hash() {
        let (key, pk) = generate_keypair();
        let problem = |c: &Chain, at: usize| -> String {
            verify_chain(&c.links, &pk, &anchored(&pk), &roots()).entries[at]
                .problem
                .clone()
                .unwrap_or_default()
        };

        let mut c = Chain::new();
        c.decision(&key);
        let unknown = AmendmentDraft::new(
            gov(99),
            c.hash_at(1),
            AmendmentKind::Overruled,
            "b",
            "n",
        )
        .unwrap();
        c.amend(&key, &unknown);
        assert!(
            problem(&c, 1).contains("is not an entry of this chain"),
            "{}",
            problem(&c, 1)
        );
        assert!(!verify_chain(&c.links, &pk, &anchored(&pk), &roots()).ok);

        // Names an entry that does not exist yet.
        let mut c = Chain::new();
        c.decision(&key);
        let forward = AmendmentDraft::new(
            gov(2),
            c.hash_at(1),
            AmendmentKind::Overruled,
            "b",
            "n",
        )
        .unwrap();
        c.amend(&key, &forward);
        c.decision(&key);
        assert!(
            problem(&c, 1).contains("not an earlier entry"),
            "{}",
            problem(&c, 1)
        );

        // Right id, wrong entry.
        let mut c = Chain::new();
        let target = c.decision(&key);
        let wrong_hash = AmendmentDraft::new(
            target,
            data_hash(&json!("some other entry")),
            AmendmentKind::Overruled,
            "b",
            "n",
        )
        .unwrap();
        c.amend(&key, &wrong_hash);
        assert!(problem(&c, 1).contains("entry_hash"), "{}", problem(&c, 1));
        assert!(
            verify_chain(&c.links, &pk, &anchored(&pk), &roots()).entries[0]
                .amended_by
                .is_empty()
        );
    }

    #[test]
    fn redaction_shape_violations_fail_verification() {
        let (key, pk) = generate_keypair();
        let amend_with = |mutate: &dyn Fn(&mut Amendment)| -> String {
            let mut c = Chain::new();
            let target = c.decision(&key);
            let mut amendment = AmendmentDraft::new(
                target,
                c.hash_at(1),
                AmendmentKind::Correction,
                "b",
                "n",
            )
            .unwrap();
            mutate(&mut amendment.amendment);
            c.amend_v1(&key, &amendment.amendment);
            let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
            assert!(!v.ok, "{v:#?}");
            v.entries[1].problem.clone().unwrap_or_default()
        };

        // `redaction` is the only way to get a well-formed one, so a
        // redaction kind without a `Redaction` can only be hand-built.
        assert_eq!(
            AmendmentDraft::new(
                gov(1),
                data_hash(&json!(null)),
                AmendmentKind::Redaction,
                "b",
                "n"
            ),
            Err(AmendmentError::MissingRedaction)
        );
        let p = amend_with(&|a| a.kind = AmendmentKind::Redaction);
        assert!(p.contains("requires a `redaction`"), "{p}");

        let p = amend_with(&|a| {
            a.redaction = Some(Redaction {
                fields: vec!["/x".into()],
                resulting_data_hash: data_hash(&json!({})),
                resulting_latest_hash: None,
            })
        });
        assert!(p.contains("only valid on kind"), "{p}");

        let p = amend_with(&|a| a.agora_governance_amendment = 3);
        assert!(p.contains("agora_governance_amendment is 3"), "{p}");

        // A version says where the texts are, and both ways round it is
        // held to it.
        let p = amend_with(&|a| a.agora_governance_amendment = 1);
        assert!(p.contains("does neither consistently"), "{p}");
        let p = amend_with(&|a| a.note = AmendmentText::Plain("n".into()));
        assert!(p.contains("does neither consistently"), "{p}");
    }

    #[test]
    fn governance_data_holds_no_number_that_is_not_a_64_bit_integer() {
        let fine = json!({"a": [1, -2, u64::MAX, i64::MIN], "b": {"c": "0.5"}});
        assert_eq!(non_integer_number(&fine), None);
        assert!(blind_data(&fine, Blind::random()).is_ok());

        for (text, pointer) in [
            (r#"{"a": {"b/c": [1, 0.5]}}"#, "/a/b~1c/1"),
            (r#"{"n": 1.0}"#, "/n"),
            (r#"{"n": 1e3}"#, "/n"),
            (r#"{"n": 18446744073709551616}"#, "/n"),
            (r#"{"n": -9223372036854775809}"#, "/n"),
        ] {
            let data: serde_json::Value = serde_json::from_str(text).unwrap();
            assert_eq!(non_integer_number(&data).as_deref(), Some(pointer));
            assert_eq!(
                blind_data(&data, Blind::random()),
                Err(BlindError::NonIntegerNumber(pointer.into())),
                "the writer refuses it"
            );
            assert_eq!(
                redact_data(&data, &["/n".into()], &amd(1), Blind::random()),
                Err(RedactError::NonIntegerNumber(pointer.into()))
            );
        }
    }

    #[test]
    fn standing_is_the_last_amendment_that_changes_it() {
        use AmendmentKind::*;
        assert_eq!(standing([]), Standing::InForce);
        assert_eq!(standing([Correction, Redaction]), Standing::InForce);
        assert_eq!(
            standing([Correction, NonPrecedential, Redaction]),
            Standing::NonPrecedential
        );
        assert_eq!(standing([Overruled, Reinstated]), Standing::InForce);
        assert_eq!(standing([Reinstated, Superseded]), Standing::Superseded);
        assert_eq!(kind_standing(Reattested), None);
        assert_eq!(kind_standing(Reinstated), Some(Standing::InForce));
    }

    #[test]
    fn a_redaction_verifies_against_the_amendment_and_nothing_else() {
        let (key, pk) = generate_keypair();
        let data = json!({
            "finding": "upheld",
            "subject": {"handle": "someone", "detail": "personal"},
        });
        let mut c = Chain::new();
        let target = c.entry(&key, data.clone());
        let amendment_id = c.next_amd();
        let (amendment, redacted) = AmendmentDraft::redaction(
            &amendment_id,
            target,
            c.hash_at(1),
            "GDPR Art. 17(1)(a)",
            "personal data removed on request",
            vec!["/subject/handle".into(), "/subject/detail".into()],
            &data,
            Blind::from([7; 32]),
            &[],
        )
        .unwrap();
        assert_eq!(c.amend(&key, &amendment), amendment_id);
        assert_eq!(redacted[BLIND_KEY], json!(Blind::from([7; 32])));

        let mut v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(v.ok, "{v:#?}");
        assert!(v.entries[0].redacted);
        assert_eq!(v.entries[0].redacted_data_hash, Some(data_hash(&redacted)));
        assert_eq!(
            redacted["subject"]["handle"],
            json!(format!("[redacted by {amendment_id}]"))
        );
        assert_eq!(redacted["finding"], json!("upheld"), "and nothing else");

        // What the server now serves verifies.
        assert!(v.check_content(&c.links[0], &redacted));
        assert_eq!(v.entries[0].content_matches, Some(true));
        assert!(v.clone().settle().ok);
        // So does the original, for anyone who kept a copy.
        assert!(v.check_content(&c.links[0], &data));

        // A second edit does not.
        let mut tampered = redacted.clone();
        tampered["finding"] = json!("overturned");
        assert!(!v.check_content(&c.links[0], &tampered));
        assert_eq!(v.entries[0].content_matches, Some(false));
        assert!(!v.settle().ok);
    }

    /// A Council record with a seat whose `raw_text` repeats its
    /// `rationale`, and one whose does not
    fn seats() -> serde_json::Value {
        json!({
            "title": "A motion",
            "rounds": [{
                "number": 1,
                "responses": [
                    {"role": "lawyer", "rationale": "Because.", "raw_text": "Because.", "vote": "yes"},
                    {"role": "artist", "rationale": "Why not.", "raw_text": "Why not?", "vote": "no"},
                ],
            }],
            "subject": {"handle": "someone"},
            BLIND_KEY: Blind::from([3; 32]),
        })
    }

    const LAWYER: &str = "/rounds/0/responses/0";

    /// An RFC 6902 patch from its JSON
    fn patch(ops: serde_json::Value) -> json_patch::Patch {
        serde_json::from_value(ops).unwrap()
    }

    /// The lawyer's `raw_text` removed as a duplicate of the rationale
    fn dedup(data: &serde_json::Value) -> Edit {
        let (raw, rationale) =
            (format!("{LAWYER}/raw_text"), format!("{LAWYER}/rationale"));
        Revision::remove_duplicates(data, &[(&raw, &rationale)]).unwrap()
    }

    fn revise(
        c: &Chain,
        target: &GovernanceLogId,
        latest: &serde_json::Value,
        patch: impl Into<Edit>,
    ) -> (AmendmentDraft, serde_json::Value) {
        AmendmentDraft::revision(
            target.clone(),
            GovernanceLogEntryType::CouncilDecision,
            c.hash_at(1),
            "Steward's record REC-2026-0001",
            "raw_text identical to the rationale removed",
            latest,
            patch,
        )
        .unwrap()
    }

    fn revision_of(draft: &AmendmentDraft) -> &Revision {
        draft.amendment.revision.as_ref().unwrap()
    }

    #[test]
    fn a_revision_overwrites_nothing_and_folds_to_the_latest() {
        let (key, pk) = generate_keypair();
        let data = seats();
        let mut c = Chain::new();
        let target = c.entry(&key, data.clone());
        let (first, v1) = revise(&c, &target, &data, dedup(&data));
        c.amend(&key, &first);
        let (second, v2) = revise(
            &c,
            &target,
            &v1,
            patch(json!([{"op": "move", "from": "/title", "path": "/motion"}])),
        );
        c.amend(&key, &second);

        let seat = &v1["rounds"][0]["responses"];
        assert!(seat[0].get("raw_text").is_none(), "removed, no marker");
        assert_eq!(seat[1]["raw_text"], json!("Why not?"), "the other stays");
        assert_eq!(v2["motion"], json!("A motion"));
        assert_eq!(v2[BLIND_KEY], data[BLIND_KEY], "blind kept");
        assert_eq!(
            latest(&data, [revision_of(&first), revision_of(&second)]).unwrap(),
            v2
        );

        let mut v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(v.ok, "{v:#?}");
        let entry = &v.entries[0];
        assert_eq!(entry.revisions, [amd(1), amd(2)]);
        assert_eq!(entry.latest_data_hash, Some(data_hash(&v2)));
        assert!(!entry.redacted && entry.redacted_data_hash.is_none());

        // The stored data is what was signed, and the latest checks too.
        assert!(v.check_content(&c.links[0], &data));
        assert!(v.check_content(&c.links[0], &v2));
        assert!(!v.check_content(&c.links[0], &v1), "not the latest");
        v.check_content(&c.links[0], &data);
        assert!(v.clone().settle().ok);

        // The restoration history is not on the wire, and a report from
        // before 0.43 still parses.
        let wire = serde_json::to_value(&v).unwrap();
        assert!(wire["entries"][0].get("history").is_none());
        let mut old = wire.clone();
        for field in ["revisions", "latest_data_hash", "superseded_revisions"] {
            old["entries"][0].as_object_mut().unwrap().remove(field);
        }
        let old: GovernanceVerification = serde_json::from_value(old).unwrap();
        assert!(old.entries[0].revisions.is_empty());
    }

    /// A revision claiming a hash its patch does not produce
    #[test]
    fn a_revision_that_does_not_produce_its_hash_fails() {
        let (key, pk) = generate_keypair();
        let data = seats();
        let mut c = Chain::new();
        let target = c.entry(&key, data.clone());
        let (mut draft, _) = revise(&c, &target, &data, dedup(&data));
        draft
            .amendment
            .revision
            .as_mut()
            .unwrap()
            .resulting_data_hash = data_hash(&json!({"something": "else"}));
        c.amend(&key, &draft);

        let mut v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(v.ok, "the chain itself is sound: {v:#?}");
        assert!(v.check_content(&c.links[0], &data), "the stored data is");
        assert!(
            v.entries[0]
                .problem
                .as_deref()
                .is_some_and(|p| p.contains("does not produce")),
            "{:?}",
            v.entries[0].problem
        );
        assert!(!v.settle().ok);

        // The same, when the link carries its data.
        c.links[0].data = Some(data);
        let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(!v.ok);
    }

    fn redact(
        c: &Chain,
        target: &GovernanceLogId,
        fields: &[&str],
        data: &serde_json::Value,
        revisions: &[&Revision],
    ) -> Result<(AmendmentDraft, serde_json::Value), RedactError> {
        AmendmentDraft::redaction(
            &c.next_amd(),
            target.clone(),
            c.hash_at(1),
            "GDPR Art. 17(1)(a)",
            "removed on request",
            fields.iter().map(|f| f.to_string()).collect(),
            data,
            Blind::from([9; 32]),
            revisions,
        )
    }

    /// A redaction after a revision rebases it over the redacted data, and
    /// erases the duplicate the revision removed along with its source
    #[test]
    fn a_revision_then_a_redaction() {
        let (key, pk) = generate_keypair();
        let data = seats();
        let mut c = Chain::new();
        let target = c.entry(&key, data.clone());
        let (revision, _) = revise(&c, &target, &data, dedup(&data));
        c.amend(&key, &revision);
        let rationale = format!("{LAWYER}/rationale");
        let (redaction, redacted) = redact(
            &c,
            &target,
            &[&rationale],
            &data,
            &[revision_of(&revision)],
        )
        .unwrap();
        c.amend(&key, &redaction);

        // The copy the revision removed is erased from the original too.
        let fields = &redaction.amendment.redaction.as_ref().unwrap().fields;
        assert_eq!(fields, &[rationale, format!("{LAWYER}/raw_text")]);
        let seat = &redacted["rounds"][0]["responses"][0];
        assert_eq!(seat["raw_text"], seat["rationale"]);
        assert!(seat["raw_text"].as_str().unwrap().starts_with("[redacted"));

        let rebased = latest(&redacted, [revision_of(&revision)]).unwrap();
        assert!(
            rebased["rounds"][0]["responses"][0]
                .get("raw_text")
                .is_none()
        );
        assert_eq!(
            redaction
                .amendment
                .redaction
                .as_ref()
                .unwrap()
                .resulting_latest_hash,
            Some(data_hash(&rebased))
        );

        let mut v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(v.ok, "{v:#?}");
        let entry = &v.entries[0];
        assert_eq!(entry.latest_data_hash, Some(data_hash(&rebased)));
        assert_eq!(entry.superseded_revisions, [amd(1)]);
        assert!(v.check_content(&c.links[0], &redacted));
        assert!(v.check_content(&c.links[0], &rebased));
        assert!(
            v.check_content(&c.links[0], &data),
            "for whoever kept a copy"
        );
        v.check_content(&c.links[0], &redacted);
        assert!(v.clone().settle().ok, "{v:#?}");

        // A redaction that lies about the rebase is caught.
        let mut c2 = Chain::new();
        let target = c2.entry(&key, data.clone());
        c2.amend(&key, &revision);
        let (mut lying, _) = redact(
            &c2,
            &target,
            &["/subject/handle"],
            &data,
            &[revision_of(&revision)],
        )
        .unwrap();
        let (_, honest) = redact(
            &c2,
            &target,
            &["/subject/handle"],
            &data,
            &[revision_of(&revision)],
        )
        .unwrap();
        lying
            .amendment
            .redaction
            .as_mut()
            .unwrap()
            .resulting_latest_hash = Some(data_hash(&json!({})));
        c2.amend(&key, &lying);
        let mut v = verify_chain(&c2.links, &pk, &anchored(&pk), &roots());
        assert!(v.check_content(&c2.links[0], &honest));
        assert!(!v.settle().ok);
    }

    /// A redaction of a revised entry that does not say what the rebase
    /// gives leaves the rebased history checked against nothing
    #[test]
    fn a_redaction_of_a_revised_entry_must_name_the_latest_hash() {
        let (key, pk) = generate_keypair();
        let data = seats();
        let mut c = Chain::new();
        let target = c.entry(&key, data.clone());
        let (revision, _) = revise(&c, &target, &data, dedup(&data));
        c.amend(&key, &revision);
        // What a caller passing no revisions produces.
        let (redaction, _) =
            redact(&c, &target, &["/subject/handle"], &data, &[]).unwrap();
        c.amend(&key, &redaction);
        let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(!v.ok);
        assert!(
            v.entries[2]
                .problem
                .as_deref()
                .is_some_and(|p| p.contains("names no resulting_latest_hash")),
            "{v:#?}"
        );
    }

    /// A revision's duplicates are checked against the version it applied
    /// to: one that removed a value unlike its `same_as` lost something
    #[test]
    fn a_false_duplicate_fails() {
        let (key, pk) = generate_keypair();
        let data = seats();
        let mut c = Chain::new();
        let target = c.entry(&key, data.clone());
        let artist = "/rounds/0/responses/1";
        let (raw, rationale) =
            (format!("{artist}/raw_text"), format!("{artist}/rationale"));
        // Hand-built: the builder refuses it.
        let (mut lying, _) = revise(
            &c,
            &target,
            &data,
            patch(json!([{"op": "remove", "path": raw}])),
        );
        let revised = apply_patch(&data, &revision_of(&lying).patch).unwrap();
        let r = lying.amendment.revision.as_mut().unwrap();
        r.duplicates = vec![(raw, rationale)];
        r.resulting_data_hash = data_hash(&revised);
        c.amend(&key, &lying);

        let mut v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(v.ok, "unread, the claim is unchecked: {v:#?}");
        assert!(v.check_content(&c.links[0], &data));
        assert!(
            v.entries[0]
                .problem
                .as_deref()
                .is_some_and(|p| p.contains("but they differ")),
            "{v:#?}"
        );
        assert!(!v.settle().ok);
    }

    /// A redaction the revisions could not be rebased over is refused
    #[test]
    fn a_redaction_that_breaks_a_revision_is_refused() {
        let (key, _) = generate_keypair();
        let data = seats();
        let mut c = Chain::new();
        let target = c.entry(&key, data.clone());
        let (moved, _) = revise(
            &c,
            &target,
            &data,
            patch(
                json!([{"op": "move", "from": "/subject/handle", "path": "/handle"}]),
            ),
        );
        c.amend(&key, &moved);
        let err =
            redact(&c, &target, &["/subject"], &data, &[revision_of(&moved)])
                .unwrap_err();
        assert!(matches!(err, RedactError::Rebase(_)), "{err}");
        // Redacting the moved value itself rebases fine.
        assert!(
            redact(
                &c,
                &target,
                &["/subject/handle"],
                &data,
                &[revision_of(&moved)]
            )
            .is_ok()
        );
    }

    /// Part of a source, or a whole one inside a redacted value, is
    /// followed to the same part of the copy
    #[test]
    fn a_redaction_follows_every_duplicate_of_what_it_erases() {
        let revision = Revision {
            patch: patch(json!([{"op": "remove", "path": "/copy"}])),
            duplicates: vec![("/copy".into(), "/source/inner".into())],
            resulting_data_hash: data_hash(&json!(null)),
        };
        let extra = |fields: &[&str]| {
            let fields: Vec<String> =
                fields.iter().map(|f| f.to_string()).collect();
            duplicates_of(&fields, &[&revision])
        };
        assert_eq!(extra(&["/source/inner"]), ["/copy"]);
        assert_eq!(extra(&["/source/inner/name"]), ["/copy/name"]);
        assert_eq!(extra(&["/source"]), ["/copy"]);
        assert!(extra(&["/source/other"]).is_empty());
        assert!(extra(&["/source/inn"]).is_empty());
    }

    /// A revision after a redaction applies to what the redaction left,
    /// and is checked against it
    #[test]
    fn a_redaction_then_a_revision() {
        let (key, pk) = generate_keypair();
        let data = seats();
        let mut c = Chain::new();
        let target = c.entry(&key, data.clone());
        let (redaction, redacted) =
            redact(&c, &target, &["/subject/handle"], &data, &[]).unwrap();
        assert_eq!(
            redaction
                .amendment
                .redaction
                .as_ref()
                .unwrap()
                .resulting_latest_hash,
            None,
            "nothing to rebase"
        );
        c.amend(&key, &redaction);
        let (revision, revised) =
            revise(&c, &target, &redacted, dedup(&redacted));
        c.amend(&key, &revision);

        let mut v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(v.ok, "{v:#?}");
        assert_eq!(v.entries[0].latest_data_hash, Some(data_hash(&revised)));
        assert!(v.entries[0].superseded_revisions.is_empty());
        assert!(v.check_content(&c.links[0], &redacted));
        assert!(v.check_content(&c.links[0], &revised));
        assert!(v.settle().ok);
    }

    #[test]
    fn a_revision_refuses_what_it_should() {
        let data = seats();
        let raw = &format!("{LAWYER}/raw_text");
        let rationale = &format!("{LAWYER}/rationale");
        let artist = "/rounds/0/responses/1";
        let dedup =
            |pairs: &[(&str, &str)]| Revision::remove_duplicates(&data, pairs);

        assert_eq!(
            dedup(&[(
                &format!("{artist}/raw_text"),
                &format!("{artist}/rationale")
            )]),
            Err(ReviseError::NotIdentical {
                path: format!("{artist}/raw_text"),
                same_as: format!("{artist}/rationale"),
            })
        );
        assert_eq!(
            dedup(&[(raw, rationale), (rationale, raw)]),
            Err(ReviseError::SourceRemoved {
                path: raw.clone(),
                same_as: rationale.clone(),
            }),
            "a same_as the patch removes"
        );
        assert_eq!(
            dedup(&[("/nope", rationale)]),
            Err(ReviseError::Unresolved("/nope".into()))
        );

        let make = |target_type, p: Edit| {
            AmendmentDraft::revision(
                gov(1),
                target_type,
                data_hash(&json!(null)),
                "b",
                "n",
                &data,
                p,
            )
            .map(|(_, v)| v)
        };
        let council = GovernanceLogEntryType::CouncilDecision;
        assert_eq!(
            make(council, patch(json!([])).into()),
            Err(ReviseError::EmptyPatch)
        );
        assert!(matches!(
            make(
                council,
                patch(json!([{"op": "remove", "path": "/nope"}])).into()
            ),
            Err(ReviseError::Patch(_))
        ));
        assert_eq!(
            make(
                council,
                patch(json!([{"op": "remove", "path": "/_blind"}])).into()
            ),
            Err(ReviseError::BlindPointer("/_blind".into()))
        );
        assert_eq!(
            make(
                council,
                patch(json!([{"op": "copy", "from": "/_blind", "path": "/b"}]))
                    .into()
            ),
            Err(ReviseError::BlindPointer("/_blind".into()))
        );
        for entry_type in [
            GovernanceLogEntryType::Amendment,
            GovernanceLogEntryType::KeyRotation,
            GovernanceLogEntryType::StewardRecord,
        ] {
            assert!(!is_revisable(entry_type));
            assert_eq!(
                make(entry_type, dedup(&[(raw, rationale)]).unwrap()),
                Err(ReviseError::NotRevisable(entry_type))
            );
        }
        assert!(is_revisable(council));
    }

    /// Added content blinds an unblinded target; nothing else does
    #[test]
    fn a_revision_that_adds_content_blinds_the_target() {
        let unblinded =
            json!({"title": "Old", "rationale": "r", "raw_text": "r"});
        let revise = |data: &serde_json::Value, p: serde_json::Value| {
            AmendmentDraft::revision(
                gov(1),
                GovernanceLogEntryType::CouncilDecision,
                data_hash(&json!(null)),
                "b",
                "n",
                data,
                patch(p),
            )
            .unwrap()
        };
        let add = json!([{"op": "add", "path": "/attachments", "value": []}]);
        let (draft, revised) = revise(&unblinded, add.clone());
        assert!(revised.get(BLIND_KEY).is_some());
        assert_eq!(revision_of(&draft).patch.len(), 2, "in the same patch");
        assert_eq!(
            latest(&unblinded, [revision_of(&draft)]).unwrap(),
            revised,
            "so the fold reproduces it"
        );

        let (_, revised) =
            revise(&unblinded, json!([{"op": "remove", "path": "/raw_text"}]));
        assert!(revised.get(BLIND_KEY).is_none(), "a removal adds nothing");

        let (draft, revised) = revise(&seats(), add);
        assert_eq!(revised[BLIND_KEY], seats()[BLIND_KEY], "never rotated");
        assert_eq!(revision_of(&draft).patch.len(), 1);
    }

    #[test]
    fn revision_shape_violations_fail_verification() {
        let (key, pk) = generate_keypair();
        let amend_with = |mutate: &dyn Fn(&mut Amendment)| -> String {
            let mut c = Chain::new();
            let target = c.entry(&key, seats());
            let (mut draft, _) = revise(&c, &target, &seats(), dedup(&seats()));
            mutate(&mut draft.amendment);
            c.amend_v1(&key, &draft.amendment);
            let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
            assert!(!v.ok, "{v:#?}");
            v.entries[1].problem.clone().unwrap_or_default()
        };
        assert_eq!(
            AmendmentDraft::new(
                gov(1),
                data_hash(&json!(null)),
                AmendmentKind::Revision,
                "b",
                "n"
            ),
            Err(AmendmentError::MissingRevision)
        );
        let p = amend_with(&|a| a.revision = None);
        assert!(p.contains("requires a `revision`"), "{p}");
        let p = amend_with(&|a| a.kind = AmendmentKind::Correction);
        assert!(p.contains("only valid on kind `revision`"), "{p}");
        let p = amend_with(&|a| a.revision.as_mut().unwrap().patch.0.clear());
        assert!(p.contains("at least one op"), "{p}");
    }

    /// Hand-written, so pinned: `wire_schemas_are_ref_free` covers `$ref`
    #[cfg(feature = "schemars")]
    #[test]
    fn the_revision_schema_describes_a_patch() {
        let schema = crate::responses::inline_schema_for::<Amendment>();
        let revision = &schema["properties"]["revision"]["properties"];
        assert_eq!(revision["patch"]["type"], json!("array"), "{schema}");
        assert_eq!(
            revision["patch"]["items"]["properties"]["op"]["enum"],
            json!(["add", "remove", "replace", "move", "copy", "test"])
        );
        assert_eq!(revision["resulting_data_hash"]["type"], json!("string"));
    }

    #[test]
    fn content_that_matches_nothing_fails_without_an_amendment() {
        let (key, pk) = generate_keypair();
        let mut c = Chain::new();
        c.entry(&key, json!({"a": 1}));
        let mut v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(!v.check_content(&c.links[0], &json!({"a": 2})));
        assert!(!v.clone().settle().ok);
        // An entry that is not in the report at all is not a pass either.
        let other = link(&key, 9, None, &json!({}), at(9));
        assert!(!v.check_content(&other, &json!({})));
    }

    #[test]
    fn tampering_with_an_amendments_data_is_caught_by_the_data_hash() {
        let (key, pk) = generate_keypair();
        let mut c = Chain::new();
        let target = c.decision(&key);
        let amendment = AmendmentDraft::new(
            target,
            c.hash_at(1),
            AmendmentKind::Overruled,
            "b",
            "overruled by a later decision",
        )
        .unwrap();
        c.amend(&key, &amendment);
        c.links[1].data.as_mut().unwrap()["note"] =
            json!("reinstated, actually");

        let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(!v.ok, "{v:#?}");
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(p.contains("does not hash to the attested data_hash"), "{p}");
        assert!(
            v.entries[0].amended_by.is_empty(),
            "an unreadable amendment has no effect"
        );
        assert!(
            v.entries[1].signature_valid && v.entries[1].link_valid,
            "the envelope is untouched — only the content is not what it \
             committed to"
        );
    }

    #[test]
    fn an_amendment_or_rotation_must_carry_its_data() {
        let (key, pk) = generate_keypair();
        let mut c = Chain::new();
        let target = c.decision(&key);
        let amendment = AmendmentDraft::new(
            target,
            c.hash_at(1),
            AmendmentKind::Correction,
            "b",
            "n",
        )
        .unwrap();
        c.amend(&key, &amendment);
        let rotation = c.routine(&pk, &generate_keypair().0);
        c.rotate(&key, &rotation);
        c.links[1].data = None;
        c.links[2].data = None;

        let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(!v.ok, "{v:#?}");
        for (i, entry_type) in [(1, "amendment"), (2, "key_rotation")] {
            let p = v.entries[i].problem.as_deref().unwrap();
            assert!(p.contains(&format!("a {entry_type} entry")), "{p}");
            assert!(p.contains("must carry its `data`"), "{p}");
        }
    }

    #[test]
    fn the_id_series_must_match_the_entry_type() {
        let (key, pk) = generate_keypair();
        let mut c = Chain::new();
        let target = c.decision(&key);
        let amendment = AmendmentDraft::new(
            target,
            c.hash_at(1),
            AmendmentKind::Correction,
            "b",
            "n",
        )
        .unwrap();
        c.push(
            &key,
            gov(7),
            GovernanceLogEntryType::Amendment,
            serde_json::to_value(&amendment.amendment).unwrap(),
            true,
        );
        let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(!v.ok, "{v:#?}");
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(p.contains("must be in the AMD- series"), "{p}");

        let mut c = Chain::new();
        c.push(
            &key,
            key_id(1),
            GovernanceLogEntryType::CouncilDecision,
            json!({}),
            false,
        );
        let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        let p = v.entries[0].problem.as_deref().unwrap();
        assert!(p.contains("reserved"), "{p}");
    }

    #[test]
    fn redact_data_replaces_whole_values_and_refuses_the_rest() {
        let id = amd(3);
        let blind = Blind::from([9; 32]);
        let data = json!({"a": {"b": [1, {"c": "secret"}]}, "d/e": "slash"});
        let out = redact_data(
            &data,
            &["/a/b/1/c".into(), "/d~1e".into()],
            &id,
            blind,
        )
        .unwrap();
        assert_eq!(out["a"]["b"][1]["c"], json!(redaction_marker(&id)));
        assert_eq!(out["d/e"], json!(redaction_marker(&id)));
        assert_eq!(out["a"]["b"][0], json!(1), "untouched");
        assert_eq!(out[BLIND_KEY], json!(blind), "a legacy entry gains one");

        assert_eq!(
            redact_data(&data, &["/a/nope".into()], &id, blind),
            Err(RedactError::Unresolved("/a/nope".into()))
        );
        assert_eq!(
            redact_data(&data, &["".into()], &id, blind),
            Err(RedactError::WholeEntry)
        );
        assert_eq!(
            redact_data(&data, &[], &id, blind),
            Err(RedactError::NoFields)
        );
        assert_eq!(
            redact_data(&data, &["/_blind".into()], &id, blind),
            Err(RedactError::BlindPointer("/_blind".into()))
        );
    }

    #[test]
    fn blind_data_is_for_objects_and_is_the_writers_to_supply() {
        let blind = Blind::from([1; 32]);
        let out = blind_data(&json!({"finding": "upheld"}), blind).unwrap();
        assert_eq!(out, json!({"finding": "upheld", "_blind": blind}));
        assert_eq!(
            blind_data(&json!([1]), blind),
            Err(BlindError::NotAnObject)
        );
        assert_eq!(blind_data(&out, blind), Err(BlindError::AlreadyBlinded));
        assert_ne!(Blind::random(), Blind::random());

        use GovernanceLogEntryType::*;
        assert!(!is_redactable(Amendment) && !is_redactable(KeyRotation));
        assert!(
            is_redactable(CouncilDecision) && is_redactable(EmergencyAction)
        );
    }

    /// The attack blinding exists for, performed. Everything the attacker
    /// uses is public after a redaction: the redacted data, the entry's
    /// original `data_hash`, and each redaction's `resulting_data_hash`.
    #[test]
    fn a_removed_value_cannot_be_confirmed_by_guessing_it() {
        // Put a guess back where a marker is and see if a public hash agrees
        fn confirms(
            public: &serde_json::Value,
            pointer: &str,
            guess: &str,
            hash: Sha256Hex,
        ) -> bool {
            let mut attempt = public.clone();
            *attempt.pointer_mut(pointer).unwrap() = json!(guess);
            data_hash(&attempt) == hash
        }
        let legacy = json!({"finding": "upheld", "handle": "someone", "city": "Utrecht"});

        // Blinded when written: the right guess confirms nothing.
        let written = blind_data(&legacy, Blind::random()).unwrap();
        let first = redact_data(
            &written,
            &["/handle".into()],
            &amd(1),
            Blind::random(),
        )
        .unwrap();
        assert!(!confirms(&first, "/handle", "someone", data_hash(&written)));

        // A second redaction of the same entry: the first one's
        // `resulting_data_hash` is public too, and covers the city.
        let second =
            redact_data(&first, &["/city".into()], &amd(2), Blind::random())
                .unwrap();
        assert!(!confirms(&second, "/city", "Utrecht", data_hash(&first)));

        // An entry from before blinding has nothing to destroy, and gains a
        // key it never had: strip it and the right guess does confirm. This
        // is the residual exposure of the entries that predate 0.27...
        let mut stripped =
            redact_data(&legacy, &["/handle".into()], &amd(3), Blind::random())
                .unwrap();
        let legacy_first = stripped.clone();
        stripped.as_object_mut().unwrap().remove(BLIND_KEY);
        assert!(confirms(
            &stripped,
            "/handle",
            "someone",
            data_hash(&legacy)
        ));
        // ...and it ends at the first redaction, which left a blind behind.
        let legacy_second = redact_data(
            &legacy_first,
            &["/city".into()],
            &amd(4),
            Blind::random(),
        )
        .unwrap();
        assert!(!confirms(
            &legacy_second,
            "/city",
            "Utrecht",
            data_hash(&legacy_first)
        ));
    }

    // -- key rotation --

    #[test]
    fn a_routine_rotation_moves_the_chain_to_the_new_key() {
        let (old, old_pk) = generate_keypair();
        let (new, new_pk) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&old);
        let rotation = c.routine(&old_pk, &new);
        let rotation_id = c.rotate(&old, &rotation);
        c.decision(&new);

        // Nothing but the root vouches for the new key, and nothing else
        // has to.
        let v = verify_chain(&c.links, &old_pk, &anchored(&old_pk), &roots());
        assert!(v.ok, "{v:#?}");
        assert_eq!(v.public_key, (&new_pk).into());
        assert_eq!(
            v.entries[1].signed_by,
            Some((&old_pk).into()),
            "the rotation itself is signed by the old key"
        );
        assert_eq!(v.entries[2].signed_by, Some((&new_pk).into()));
        assert!(v.unanchored_keys.is_empty());
        assert!(v.repudiated.is_empty());
        assert_eq!(v.keys.len(), 2);
        assert_eq!(v.keys[0].public_key, (&old_pk).into());
        assert_eq!(v.keys[0].from_seq, 1);
        assert_eq!(v.keys[0].through_seq, Some(2));
        assert_eq!(v.keys[0].status, KeyStatus::Retired);
        assert_eq!(v.keys[0].introduced_by, None);
        assert_eq!(v.keys[0].retired_by.as_ref(), Some(&rotation_id));
        assert!(v.keys[0].certified, "retroactively, by the rotation");
        assert_eq!(v.keys[1].from_seq, 3);
        assert_eq!(v.keys[1].through_seq, None);
        assert_eq!(v.keys[1].status, KeyStatus::Active);
        assert_eq!(v.keys[1].introduced_by.as_ref(), Some(&rotation_id));
        assert!(v.keys[1].certified);
    }

    #[test]
    fn the_old_key_cannot_sign_after_a_routine_rotation() {
        let (old, old_pk) = generate_keypair();
        let (new, _) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&old);
        let rotation = c.routine(&old_pk, &new);
        c.rotate(&old, &rotation);
        c.decision(&old);

        let v = verify_chain(&c.links, &old_pk, &anchored(&old_pk), &roots());
        assert!(!v.ok, "{v:#?}");
        assert!(!v.entries[2].signature_valid);
        assert!(
            v.entries[2].link_valid,
            "the linkage is fine; the key is not"
        );
    }

    /// The scenario the root exists for: the online key alone moves
    /// nothing, however well-formed the rotation it signs.
    #[test]
    fn the_online_key_cannot_certify_its_own_successor() {
        let (old, old_pk) = generate_keypair();
        let (thief, _) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&old);
        let mut rotation = c.routine(&old_pk, &thief);
        // Signed by the stolen online key instead of a root.
        let statement = rotation.certificate.statement.clone();
        rotation.certificate = certify(&[&old], statement);
        c.rotate(&old, &rotation);
        c.decision(&thief);

        let v = verify_chain(&c.links, &old_pk, &anchored(&old_pk), &roots());
        assert!(!v.ok, "{v:#?}");
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(p.contains("0 valid root signature"), "{p}");
        assert_eq!(v.public_key, (&old_pk).into(), "the chain does not move");
        assert!(!v.entries[2].signature_valid);
        assert_eq!(v.keys.len(), 1);
    }

    #[test]
    fn a_certificate_counts_distinct_known_roots_only() {
        let (old, old_pk) = generate_keypair();
        let (new, _) = generate_keypair();
        let (stranger, _) = generate_keypair();
        let two_of_two = RootSet::new(
            [
                (&root(1).verifying_key()).into(),
                (&root(2).verifying_key()).into(),
            ],
            2,
        );
        let verdict = |signers: &[&SigningKey], roots: &RootSet| {
            let mut c = Chain::new();
            c.decision(&old);
            let mut rotation = c.routine(&old_pk, &new);
            let statement = rotation.certificate.statement.clone();
            rotation.certificate = certify(signers, statement);
            // The genesis certificate is held to the same threshold.
            let genesis = KeyCertStatement::genesis((&old_pk).into());
            rotation.outgoing_certificate =
                Some(certify(&[&root(1), &root(2)], genesis));
            c.rotate(&old, &rotation);
            verify_chain(&c.links, &old_pk, &anchored(&old_pk), roots)
        };

        assert!(verdict(&[&root(1), &root(2)], &two_of_two).ok);
        assert!(verdict(&[&root(2)], &roots()).ok, "either root, 1-of-2");

        for (signers, why) in [
            (vec![&root(1)], "below the threshold"),
            (vec![&root(1), &root(1)], "one root twice is one root"),
            (vec![&root(1), &stranger], "an unknown root is nobody"),
            (vec![], "unsigned"),
        ] {
            let v = verdict(&signers, &two_of_two);
            assert!(!v.ok, "{why}: {v:#?}");
            let p = v.entries[1].problem.as_deref().unwrap();
            assert!(p.contains("where 2 are needed"), "{why}: {p}");
        }

        // An unknown signer beside a sufficient set is not an error.
        assert!(verdict(&[&stranger, &root(1)], &roots()).ok);
    }

    #[test]
    fn a_certificate_is_good_for_one_statement_at_one_position() {
        let (old, old_pk) = generate_keypair();
        let (new, new_pk) = generate_keypair();
        let (other, other_pk) = generate_keypair();
        let anchor = anchored(&old_pk);

        // Certified for the position right after entry 1, appended one
        // entry later. The proof of possession is rebuilt for the new
        // position; the certificate cannot be.
        let mut c = Chain::new();
        c.decision(&old);
        let early = c.routine(&old_pk, &new);
        c.decision(&old);
        let mut rotation = c.routine(&old_pk, &new);
        rotation.certificate = early.certificate;
        c.rotate(&old, &rotation);
        let v = verify_chain(&c.links, &old_pk, &anchor, &roots());
        assert!(!v.ok, "{v:#?}");
        let p = v.entries[2].problem.as_deref().unwrap();
        assert!(
            p.contains("different key, purpose or chain position"),
            "{p}"
        );
        assert_eq!(v.public_key, (&old_pk).into());

        // Certified for one key, presented for another.
        let mut c = Chain::new();
        c.decision(&old);
        let for_new = c.routine(&old_pk, &new);
        let mut rotation = c.routine(&old_pk, &other);
        rotation.certificate = for_new.certificate;
        c.rotate(&old, &rotation);
        let v = verify_chain(&c.links, &old_pk, &anchor, &roots());
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(
            p.contains("different key, purpose or chain position"),
            "{p}"
        );

        // The statement altered after signing, to match.
        let mut c = Chain::new();
        c.decision(&old);
        let mut rotation = c.routine(&old_pk, &other);
        rotation.certificate = for_new_at(&c, &new_pk);
        rotation.certificate.statement.key = (&other_pk).into();
        c.rotate(&old, &rotation);
        let v = verify_chain(&c.links, &old_pk, &anchor, &roots());
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(p.contains("0 valid root signature"), "{p}");

        // A routine certificate does not authorize a compromise.
        let mut c = Chain::new();
        c.decision(&old);
        c.decision(&old);
        let mut rotation = c.compromise(&old_pk, &new, 1);
        rotation.certificate = for_new_at(&c, &new_pk);
        c.rotate(&new, &rotation);
        let v = verify_chain(&c.links, &old_pk, &anchor, &roots());
        assert!(!v.ok);
        assert!(v.repudiated.is_empty(), "{v:#?}");
        assert_eq!(v.public_key, (&old_pk).into());
    }

    /// The same signature over the same JSON without the domain prefix —
    /// what a root key tricked into signing "just some JSON" would produce
    #[test]
    fn a_root_signature_without_the_domain_prefix_certifies_nothing() {
        use ed25519_dalek::Signer;
        let (old, old_pk) = generate_keypair();
        let (new, _) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&old);
        let mut rotation = c.routine(&old_pk, &new);
        let statement = rotation.certificate.statement.clone();
        let bare = canonical_json(&serde_json::to_value(&statement).unwrap());
        assert_eq!(
            statement.signed_bytes(),
            [ROOT_DOMAIN, bare.as_slice()].concat()
        );
        rotation.certificate =
            KeyCertificate::unsigned(statement).with(RootSignature {
                root_key: (&root(1).verifying_key()).into(),
                signature: root(1).sign(&bare).into(),
            });
        c.rotate(&old, &rotation);
        let v = verify_chain(&c.links, &old_pk, &anchored(&old_pk), &roots());
        assert!(!v.ok, "{v:#?}");
        assert_eq!(v.public_key, (&old_pk).into());
    }

    #[test]
    fn the_first_rotation_carries_the_genesis_certificate_and_only_it_does() {
        let (k1, k1_pk) = generate_keypair();
        let (k2, k2_pk) = generate_keypair();
        let (k3, _) = generate_keypair();
        let genesis =
            || certify(&[&root(1)], KeyCertStatement::genesis((&k1_pk).into()));

        // Missing.
        let mut c = Chain::new();
        c.decision(&k1);
        let mut rotation = c.routine(&k1_pk, &k2);
        rotation.outgoing_certificate = None;
        c.rotate(&k1, &rotation);
        let v = verify_chain(&c.links, &k1_pk, &anchored(&k1_pk), &roots());
        assert!(!v.ok);
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(p.contains("genesis key's outgoing_certificate"), "{p}");
        assert_eq!(v.public_key, (&k1_pk).into());

        // For some other key.
        let mut c = Chain::new();
        c.decision(&k1);
        let rotation = c.routine(&k1_pk, &k2).with_outgoing(certify(
            &[&root(1)],
            KeyCertStatement::genesis((&k2_pk).into()),
        ));
        c.rotate(&k1, &rotation);
        let v = verify_chain(&c.links, &k1_pk, &anchored(&k1_pk), &roots());
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(p.starts_with("outgoing_certificate:"), "{p}");

        // Present, and it is what vouches for a genesis key no anchor
        // knows.
        let mut c = Chain::new();
        c.decision(&k1);
        let rotation = c.routine(&k1_pk, &k2);
        assert_eq!(rotation.outgoing_certificate, Some(genesis()));
        c.rotate(&k1, &rotation);
        let v = verify_chain(&c.links, &k1_pk, &KeyAnchor::default(), &roots());
        assert!(v.ok, "{v:#?}");
        assert!(v.unanchored_keys.is_empty(), "{v:#?}");

        // A second one, later, is refused.
        let again = c.routine(&k2_pk, &k3).with_outgoing(genesis());
        c.rotate(&k2, &again);
        let v = verify_chain(&c.links, &k1_pk, &anchored(&k1_pk), &roots());
        assert!(!v.ok);
        let p = v.entries[2].problem.as_deref().unwrap();
        assert!(p.contains("nowhere else"), "{p}");
    }

    #[test]
    fn a_forged_proof_of_possession_is_rejected() {
        let (old, old_pk) = generate_keypair();
        let (_, new_pk) = generate_keypair();
        let (thief, _) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&old);
        // A rotation to a key nobody holds, certified in good faith: the
        // proof is signed by the old key instead of by `new_key` itself.
        let mut rotation = c.routine(&old_pk, &thief);
        rotation.new_key = (&new_pk).into();
        rotation.certificate = for_new_at(&c, &new_pk);
        let statement = rotation.statement(c.prev_hash());
        rotation.proof = crypto::sign(
            &old,
            statement.hash().as_bytes(),
            rotation.proof_signed_at,
        )
        .into();
        c.rotate(&old, &rotation);

        assert_eq!(
            rotation.verify_proof(c.links[1].attestation.prev_hash),
            Err(RotationError::BadProof)
        );
        let v = verify_chain(&c.links, &old_pk, &anchored(&old_pk), &roots());
        assert!(!v.ok, "{v:#?}");
        assert!(
            v.entries[1]
                .problem
                .as_deref()
                .unwrap()
                .contains("proof of possession")
        );
        assert_eq!(v.public_key, (&old_pk).into(), "the chain does not move");
    }

    #[test]
    fn a_compromise_repudiates_the_window_and_a_reattestation_restores_one() {
        let (old, old_pk) = generate_keypair();
        let (new, new_pk) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&old); // 1 — the last entry anyone trusts
        c.decision(&old); // 2 — inside the window
        let reattested = c.decision(&old); // 3 — inside, later vouched for
        let rotation = c.compromise(&old_pk, &new, 1);
        let rotation_id = c.rotate(&new, &rotation); // 4 — signed by the NEW key
        let vouch = AmendmentDraft::new(
            reattested,
            c.hash_at(3),
            AmendmentKind::Reattested,
            "Art. VII",
            "independently verified; the Steward vouches for it",
        )
        .unwrap();
        let vouch_id = c.amend(&new, &vouch); // 5

        let v = verify_chain(&c.links, &old_pk, &anchored(&old_pk), &roots());
        assert!(
            v.ok,
            "repudiation is a declared state, not a defect: {v:#?}"
        );
        assert_eq!(v.repudiated, vec![gov(2)]);
        assert!(v.entries[1].repudiated);
        assert!(!v.entries[2].repudiated);
        assert_eq!(v.entries[2].reattested_by, vec![vouch_id.clone()]);
        assert_eq!(v.entries[2].amended_by, vec![vouch_id]);
        assert_eq!(v.entries[3].signed_by, Some((&new_pk).into()));
        assert_eq!(v.public_key, (&new_pk).into());
        assert_eq!(v.keys.len(), 2);
        assert_eq!(v.keys[0].status, KeyStatus::Compromised);
        assert_eq!(
            v.keys[0].through_seq,
            Some(1),
            "trusted through the last trusted entry, not through the \
             declaration"
        );
        assert_eq!(v.keys[0].retired_by.as_ref(), Some(&rotation_id));
        assert_eq!(v.keys[1].from_seq, 4, "the declaration is its own first");
    }

    /// The root says where the window opens. A declaration cannot trust
    /// the old key one entry further than its certificate does.
    #[test]
    fn last_trusted_is_the_roots_to_say() {
        let (old, old_pk) = generate_keypair();
        let (new, _) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&old); // 1
        c.decision(&old); // 2
        let mut rotation = c.compromise(&old_pk, &new, 1);
        rotation.certificate.statement.last_trusted = Some(c.head(2));
        c.rotate(&new, &rotation);
        let v = verify_chain(&c.links, &old_pk, &anchored(&old_pk), &roots());
        assert!(!v.ok, "{v:#?}");
        assert!(v.repudiated.is_empty());
        assert_eq!(v.public_key, (&old_pk).into());
    }

    #[test]
    fn a_stolen_key_cannot_be_rotated_back_in() {
        // K1 is compromised and replaced by K2. The thief, still holding
        // K1, declares a "compromise" of K2 naming K1 as the new key — and
        // even a root certificate would not bring a key back.
        let (k1, k1_pk) = generate_keypair();
        let (k2, k2_pk) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&k1); // 1
        let real = c.compromise(&k1_pk, &k2, 1);
        c.rotate(&k2, &real); // 2
        c.decision(&k2); // 3
        let honest =
            verify_chain(&c.links, &k1_pk, &anchored(&k1_pk), &roots());
        assert!(honest.ok, "{honest:#?}");

        let hijack = c.compromise(&k2_pk, &k1, 3);
        c.rotate(&k1, &hijack); // 4 — signed by the stolen key
        c.decision(&k1); // 5

        let v = verify_chain(&c.links, &k1_pk, &anchored(&k1_pk), &roots());
        assert!(!v.ok);
        assert_eq!(v.public_key, (&k2_pk).into(), "the chain stays with K2");
        let p = v.entries[3].problem.as_deref().unwrap();
        assert!(p.contains("never brought back"), "{p}");
        assert!(!v.entries[3].signature_valid, "{:#?}", v.entries[3]);
        assert!(!v.entries[4].signature_valid, "K1 signs nothing again");
        assert_eq!(v.keys.len(), 2);
        assert_eq!(v.keys[1].status, KeyStatus::Active);
    }

    #[test]
    fn a_routine_rotation_cannot_reuse_a_key_either() {
        let (k1, k1_pk) = generate_keypair();
        let (k2, k2_pk) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&k1);
        let out = c.routine(&k1_pk, &k2);
        c.rotate(&k1, &out);
        let back = c.routine(&k2_pk, &k1);
        c.rotate(&k2, &back);
        let v = verify_chain(&c.links, &k1_pk, &anchored(&k1_pk), &roots());
        assert!(!v.ok);
        assert!(
            v.entries[2]
                .problem
                .as_deref()
                .unwrap()
                .contains("never brought back"),
            "{:#?}",
            v.entries[2]
        );
        assert_eq!(v.public_key, (&k2_pk).into());
    }

    #[test]
    fn a_forged_entry_has_no_effects() {
        let (steward, steward_pk) = generate_keypair();
        let (forger, _) = generate_keypair();
        let anchor = anchored(&steward_pk);
        let mut c = Chain::new();
        let target = c.decision(&steward); // 1
        let fake = AmendmentDraft::new(
            target,
            c.hash_at(1),
            AmendmentKind::Overruled,
            "none",
            "overruled, says nobody with the key",
        )
        .unwrap();
        c.amend(&forger, &fake); // 2 — not signed by the key in force
        // Certified, even: a certificate is not a licence to skip the old
        // key's signature on a routine rotation.
        let grab = c.routine(&steward_pk, &forger);
        c.rotate(&forger, &grab); // 3 — likewise

        let v = verify_chain(&c.links, &steward_pk, &anchor, &roots());
        assert!(!v.ok);
        assert!(v.entries[0].amended_by.is_empty(), "{:#?}", v.entries[0]);
        assert_eq!(v.public_key, (&steward_pk).into());
        assert_eq!(v.keys.len(), 1);
        assert!(v.unanchored_keys.is_empty());
    }

    #[test]
    fn a_repeated_id_is_a_problem() {
        let (key, pk) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&key);
        c.gov = 0;
        c.decision(&key); // GOV-2026-0001 again
        let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(!v.ok);
        assert!(v.entries.iter().all(|e| {
            e.problem
                .as_deref()
                .is_some_and(|p| p.contains("more than once"))
        }));
    }

    #[test]
    fn a_second_compromise_cannot_anchor_inside_the_first_window() {
        let (k1, k1_pk) = generate_keypair();
        let (k2, _) = generate_keypair();
        let (k3, _) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&k1); // 1 — trusted
        c.decision(&k1); // 2 — inside the first window
        let first = c.compromise(&k1_pk, &k2, 1);
        c.rotate(&k2, &first); // 3
        let second = c.compromise(&k1_pk, &k3, 2);
        c.rotate(&k3, &second); // 4

        let v = verify_chain(&c.links, &k1_pk, &anchored(&k1_pk), &roots());
        assert!(!v.ok);
        let p = v.entries[3].problem.as_deref().unwrap();
        assert!(p.contains("repudiated"), "{p}");
        assert_eq!(v.keys.len(), 2, "K1 and K2; K3 never took the chain");
        assert_eq!(v.keys[0].through_seq, Some(1));
    }

    #[test]
    fn an_uncertified_compromise_fails_closed() {
        let (old, old_pk) = generate_keypair();
        let (new, new_pk) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&old);
        c.decision(&old);
        let mut rotation = c.compromise(&old_pk, &new, 1);
        let statement = rotation.certificate.statement.clone();
        rotation.certificate = certify(&[&new], statement);
        c.rotate(&new, &rotation);

        // Being in an anchor does not help: only the root moves the chain.
        let anchor = anchored(&old_pk).with((&new_pk).into());
        let v = verify_chain(&c.links, &old_pk, &anchor, &roots());
        assert!(!v.ok, "{v:#?}");
        let p = v.entries[2].problem.as_deref().unwrap();
        assert!(p.contains("0 valid root signature"), "{p}");
        assert!(!v.entries[2].signature_valid, "checked under the old key");
        assert!(v.repudiated.is_empty(), "and nothing is repudiated");
        assert_eq!(v.public_key, (&old_pk).into());
    }

    /// A key stolen before anyone knew: the Steward rotates routinely,
    /// then learns the old key was already out, and names a head from
    /// before the rotation. The rotation is void with the rest of the
    /// window.
    #[test]
    fn a_rotation_inside_the_window_is_void_with_it() {
        let (steward, steward_pk) = generate_keypair();
        let (successor, _) = generate_keypair();
        let (recovery, recovery_pk) = generate_keypair();

        let mut c = Chain::new();
        c.decision(&steward); // 1 — the last entry anyone trusts
        c.decision(&steward); // 2 — the thief's, as it turns out
        let routine = c.routine(&steward_pk, &successor);
        c.rotate(&steward, &routine); // 3
        c.decision(&successor); // 4

        let declaration = c.compromise(&steward_pk, &recovery, 1);
        c.rotate(&recovery, &declaration); // 5

        let v = verify_chain(
            &c.links,
            &steward_pk,
            &anchored(&steward_pk),
            &roots(),
        );
        assert!(v.ok, "{v:#?}");
        assert_eq!(v.repudiated, vec![gov(2), key_id(1), gov(3)]);
        assert_eq!(v.public_key, (&recovery_pk).into());
        assert_eq!(v.keys.len(), 2, "the successor is not part of history");
        assert_eq!(v.keys[0].public_key, (&steward_pk).into());
        assert_eq!(v.keys[0].status, KeyStatus::Compromised);
        assert!(
            v.keys[0].certified,
            "the genesis certificate rode in on the voided rotation and \
             is the root's word all the same"
        );
        assert_eq!(v.keys[1].public_key, (&recovery_pk).into());
    }

    #[test]
    fn a_compromise_must_name_a_real_head_and_the_key_that_held_it() {
        let (old, old_pk) = generate_keypair();
        let (new, new_pk) = generate_keypair();
        let anchor = anchored(&old_pk);

        // A head whose hash is not that entry's — certified, so the only
        // thing wrong is what the chain says about it.
        let mut c = Chain::new();
        c.decision(&old);
        let mut trusted = c.head(1);
        trusted.entry_hash = data_hash(&json!("nope"));
        let statement = KeyCertStatement::compromise(
            (&new_pk).into(),
            2,
            c.prev_hash(),
            trusted,
        );
        let mut rotation = c.compromise(&old_pk, &new, 1);
        rotation.certificate = certify(&[&root(1)], statement);
        c.rotate(&new, &rotation);
        let v = verify_chain(&c.links, &old_pk, &anchor, &roots());
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(p.contains("last_trusted"), "{p}");

        // An old_key that was never in force.
        let (_, other_pk) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&old);
        let rotation = c.compromise(&other_pk, &new, 1);
        c.rotate(&new, &rotation);
        let v = verify_chain(&c.links, &old_pk, &anchor, &roots());
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(p.contains("old_key is not the key"), "{p}");

        // A compromise whose certificate names no head at all.
        let mut c = Chain::new();
        c.decision(&old);
        let mut rotation = c.compromise(&old_pk, &new, 1);
        rotation.certificate.statement.last_trusted = None;
        c.rotate(&new, &rotation);
        let v = verify_chain(&c.links, &old_pk, &anchor, &roots());
        let p = v.entries[1].problem.as_deref().unwrap();
        assert!(p.contains("must name last_trusted"), "{p}");
    }

    #[test]
    fn a_rotation_carries_no_free_text() {
        let (old, old_pk) = generate_keypair();
        let (new, _) = generate_keypair();
        let mut c = Chain::new();
        c.decision(&old);
        let rotation = c.routine(&old_pk, &new);
        let mut value = serde_json::to_value(&rotation).unwrap();
        assert!(serde_json::from_value::<KeyRotation>(value.clone()).is_ok());
        value["note"] = json!("at the request of …");
        assert!(serde_json::from_value::<KeyRotation>(value).is_err());

        let mut head = serde_json::to_value(c.head(1)).unwrap();
        head["comment"] = json!("the last one I remember signing");
        assert!(serde_json::from_value::<TrustedHead>(head).is_err());

        let mut statement =
            serde_json::to_value(&rotation.certificate.statement).unwrap();
        statement["comment"] = json!("signed in the kitchen");
        assert!(serde_json::from_value::<KeyCertStatement>(statement).is_err());
    }

    #[test]
    fn the_root_statement_bytes_are_pinned() {
        let key: PublicKeyHex = PUBLISHED_KEYS[0].parse().unwrap();
        assert_eq!(
            String::from_utf8(KeyCertStatement::genesis(key).signed_bytes())
                .unwrap(),
            "agora-governance-root-v1\n\
             {\"agora_governance_key_cert\":1,\"from_seq\":1,\
             \"key\":\"ebb3091dd328f1463362c171121921b2fe14628e3fc4c145deaccefb85c0e78a\",\
             \"last_trusted\":null,\"prev_hash\":null,\"purpose\":\"genesis\"}"
        );

        // The same statement `governance/root/root_sign.py --self-test`
        // pins in the agora repository: the tool that signs and the
        // verifiers that check must mean the same bytes.
        let statement = KeyCertStatement::compromise(
            Sha256Hex::from([0xab; 32]).to_string().parse().unwrap(),
            15,
            Some([0xcd; 32].into()),
            TrustedHead {
                id: gov(10),
                chain_seq: 11,
                entry_hash: [0xef; 32].into(),
            },
        );
        assert_eq!(
            Sha256Hex::from(<[u8; 32]>::from(Sha256::digest(
                statement.signed_bytes()
            )))
            .to_string(),
            "633685771e08be126fd12ca4eb98c77120e5868236ff541ecba85ce6a21e6b68"
        );
    }

    #[test]
    fn root_keys_are_curve_points_and_make_a_root_set() {
        let roots = RootSet::published();
        assert_eq!(roots.keys().count(), ROOT_KEYS.len());
        assert_eq!(roots.threshold(), ROOT_THRESHOLD);
        assert!(ROOT_THRESHOLD >= 1 && ROOT_THRESHOLD <= ROOT_KEYS.len());
        for root in ROOT_KEYS {
            let key: PublicKeyHex = root.parse().unwrap();
            assert!(roots.contains(&key));
            assert!(
                key.to_verifying_key().is_ok(),
                "{root} is not a valid Ed25519 public key"
            );
            assert!(
                !PUBLISHED_KEYS.contains(root),
                "a root key never signs entries"
            );
        }
        assert_eq!(RootSet::new([], 0).threshold(), 1);
    }

    #[test]
    fn a_genesis_key_outside_the_anchor_is_reported_not_rejected() {
        let (key, pk) = generate_keypair();
        let c = chain(&key, 2);
        let v = verify_chain(&c, &pk, &KeyAnchor::default(), &roots());
        assert!(v.ok, "{v:#?}");
        assert_eq!(v.unanchored_keys, vec![PublicKeyHex::from(&pk)]);
        assert_eq!(v.keys.len(), 1);
        assert_eq!(v.keys[0].status, KeyStatus::Active);
        assert_eq!(v.keys[0].from_seq, 1);
        assert_eq!(v.keys[0].through_seq, None);
    }

    #[test]
    fn published_keys_are_curve_points_and_make_an_anchor() {
        let anchor = KeyAnchor::published();
        assert!(!anchor.is_empty());
        assert_eq!(anchor.keys().count(), PUBLISHED_KEYS.len());
        for published in PUBLISHED_KEYS {
            let key: PublicKeyHex = published.parse().unwrap();
            assert!(anchor.contains(&key));
            assert!(
                key.to_verifying_key().is_ok(),
                "{published} is not a valid Ed25519 public key"
            );
        }
        let (_, other) = generate_keypair();
        assert!(!anchor.contains(&(&other).into()));
        assert!(
            anchor
                .clone()
                .with((&other).into())
                .contains(&(&other).into())
        );
    }

    // -- the wire --

    #[test]
    fn amendments_and_rotations_round_trip_as_entry_data() {
        let (key, pk) = generate_keypair();
        let amendment = AmendmentDraft::new(
            gov(1),
            data_hash(&json!("x")),
            AmendmentKind::Superseded,
            "Art. VI § 2",
            "superseded by GOV-2026-0009",
        )
        .unwrap()
        .with_authority(gov(9))
        .with_rationale("the later decision covers the same subject");
        let AmendmentDraft { amendment, texts } = amendment;
        let value = serde_json::to_value(&amendment).unwrap();
        assert_eq!(value["kind"], "superseded");
        assert_eq!(value["agora_governance_amendment"], 2);
        assert!(value.get("redaction").is_none(), "{value}");
        let text = value.to_string();
        assert!(!text.contains("Art. VI"), "no text in signed data: {text}");
        assert!(!text.contains("salt"), "and no salt: {text}");
        assert_eq!(
            value["note"]["commitment"],
            texts
                .note
                .as_ref()
                .unwrap()
                .commitment()
                .commitment
                .to_string()
        );
        assert_eq!(
            serde_json::from_value::<Amendment>(value).unwrap(),
            amendment
        );
        let beside = serde_json::to_value(&texts).unwrap();
        assert_eq!(beside["basis"]["text"], "Art. VI § 2");
        assert_eq!(
            serde_json::from_value::<AmendmentTexts>(beside).unwrap(),
            texts
        );

        // Version 1, as the platform's three are, still reads.
        let legacy = json!({
            "agora_governance_amendment": 1,
            "target": "GOV-2026-0001",
            "target_entry_hash": data_hash(&json!("x")),
            "kind": "non_precedential",
            "authority": "GOV-2026-0005",
            "basis": "§1",
            "note": "diagnostic finding",
        });
        let legacy: Amendment = serde_json::from_value(legacy).unwrap();
        assert_eq!(legacy.validate(), Ok(()));
        assert_eq!(legacy.basis, AmendmentText::Plain("§1".into()));

        let mut c = Chain::new();
        c.decision(&key);
        let rotation = c.compromise(&pk, &generate_keypair().0, 1);
        let value = serde_json::to_value(&rotation).unwrap();
        assert_eq!(value["agora_governance_key_rotation"], 2);
        assert_eq!(value["reason"], "compromise");
        let statement = &value["certificate"]["statement"];
        assert_eq!(statement["purpose"], "compromise");
        assert_eq!(statement["last_trusted"]["chain_seq"], 1);
        assert_eq!(
            value["outgoing_certificate"]["statement"]["purpose"],
            "genesis"
        );
        assert!(value.get("note").is_none(), "{value}");
        assert_eq!(
            serde_json::from_value::<KeyRotation>(value).unwrap(),
            rotation
        );

        let notice =
            AmendmentNotice::new(amd(1), at(0), &amendment, Some(&texts));
        let value = serde_json::to_value(&notice).unwrap();
        assert_eq!(value["id"], "AMD-2026-0001");
        assert_eq!(value["note"], "superseded by GOV-2026-0009");
        assert_eq!(
            serde_json::from_value::<AmendmentNotice>(value).unwrap(),
            notice
        );

        // The rationale erased: the label stays, and nothing else moves.
        let erased = AmendmentTexts {
            rationale: None,
            ..texts.clone()
        };
        let notice =
            AmendmentNotice::new(amd(1), at(0), &amendment, Some(&erased));
        assert_eq!(notice.note, "superseded by GOV-2026-0009");
        assert_eq!(notice.rationale.as_deref(), Some(WITHHELD_TEXT));
        let notice = AmendmentNotice::new(amd(1), at(0), &amendment, None);
        assert_eq!(notice.basis, WITHHELD_TEXT);
        let notice = AmendmentNotice::new(amd(1), at(0), &legacy, None);
        assert_eq!(notice.note, "diagnostic finding");
    }

    /// The verifier hashes the raw `data` value, so a field it has never
    /// heard of neither breaks it nor escapes the signature — and an
    /// amendment written without one verifies just the same.
    #[test]
    fn an_amendment_verifies_with_or_without_its_optional_fields() {
        let (key, pk) = generate_keypair();
        let mut c = Chain::new();
        let target = c.decision(&key);
        let bare = AmendmentDraft::new(
            target.clone(),
            c.hash_at(1),
            AmendmentKind::Correction,
            "clerical",
            "typo in the citation",
        )
        .unwrap();
        assert!(
            serde_json::to_value(&bare.amendment)
                .unwrap()
                .get("rationale")
                .is_none()
        );
        c.amend(&key, &bare);
        let full = bare.clone().with_rationale("at length: …");
        c.amend(&key, &full);
        // And a field from a future version of the shape.
        let mut future = serde_json::to_value(&full.amendment).unwrap();
        future["superseded_by_something_new"] = json!(["later"]);
        c.push(
            &key,
            amd(3),
            GovernanceLogEntryType::Amendment,
            future,
            true,
        );

        let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        assert!(v.ok, "{v:#?}");
        assert_eq!(
            v.entries[0].amended_by,
            vec![amd(1), amd(2), amd(3)],
            "all three name the target"
        );
    }

    /// Pre-0.26 JSON — no `data`, no `signed_by`, no repudiation — still
    /// parses, because every field added since is `#[serde(default)]`.
    #[test]
    fn pre_0_26_wire_still_deserializes() {
        let link: GovernanceChainLink = serde_json::from_value(json!({
            "id": "GOV-2026-0001",
            "entry_type": "council_decision",
            "created_at": "2023-11-14T22:13:20.123456Z",
            "attestation": {
                "envelope_version": 1,
                "chain_seq": 1,
                "prev_hash": null,
                "data_hash": "00".repeat(32),
                "entry_hash": "11".repeat(32),
                "signature": "22".repeat(64),
                "signed_at": "2023-11-14T22:13:21Z",
                "retroactive": false,
            },
        }))
        .unwrap();
        assert!(link.data.is_none());
        assert!(
            serde_json::to_value(&link).unwrap().get("data").is_none(),
            "and a link without data does not grow a null field"
        );

        let verdict: EntryVerdict = serde_json::from_value(json!({
            "id": "GOV-2026-0001",
            "chain_seq": 1,
            "signature_valid": true,
            "link_valid": true,
            "content_matches": null,
            "retroactive": false,
            "out_of_order": false,
            "amended_by": [],
        }))
        .unwrap();
        assert!(!verdict.repudiated && !verdict.redacted);
        assert!(verdict.signed_by.is_none());
        assert!(verdict.reattested_by.is_empty());

        let verification: GovernanceVerification =
            serde_json::from_value(json!({
                "public_key": "33".repeat(32),
                "ok": true,
                "head": "GOV-2026-0001",
                "entries": [],
            }))
            .unwrap();
        assert!(verification.keys.is_empty());
        assert!(verification.unanchored_keys.is_empty());
        assert!(verification.repudiated.is_empty());
    }

    #[test]
    fn the_report_round_trips() {
        let (key, pk) = generate_keypair();
        let mut c = Chain::new();
        let target = c.decision(&key);
        let amendment = AmendmentDraft::new(
            target,
            c.hash_at(1),
            AmendmentKind::Overruled,
            "b",
            "n",
        )
        .unwrap();
        c.amend(&key, &amendment);
        let v = verify_chain(&c.links, &pk, &anchored(&pk), &roots());
        let text = serde_json::to_string(&v).unwrap();
        assert_eq!(
            serde_json::from_str::<GovernanceVerification>(&text).unwrap(),
            v
        );

        let keys = GovernanceSigningKeys { keys: v.keys };
        let value = serde_json::to_value(&keys).unwrap();
        assert!(value["keys"].is_array(), "an object, not a bare array");
        assert_eq!(value["keys"][0]["status"], "active");
        assert_eq!(
            serde_json::from_value::<GovernanceSigningKeys>(value).unwrap(),
            keys
        );
    }

    /// The envelope is version 1 and there is a live chain signed under it:
    /// these bytes and this hash are load-bearing, not a snapshot to
    /// re-bless when something changes them.
    #[test]
    fn envelope_v1_preimage_and_hash_are_pinned() {
        let envelope = Envelope::new(
            gov(6),
            GovernanceLogEntryType::CouncilDecision,
            at(0),
            Some(Sha256Hex::from([0x11; 32])),
            data_hash(&json!({"outcome": "approved", "title": "Ratification"})),
        );
        assert_eq!(
            String::from_utf8(envelope.preimage()).unwrap(),
            "{\"agora_governance_log\":1,\"id\":\"GOV-2026-0006\",\
             \"entry_type\":\"council_decision\",\
             \"created_at\":1700000000123456,\
             \"prev_hash\":\"1111111111111111111111111111111111111111111111111111111111111111\",\
             \"data_hash\":\"a4adf645ae3f60c56484d01aea87d6d490321d7fc66b1607df14b023fe567c7b\"}"
        );
        assert_eq!(
            envelope.entry_hash().to_hex(),
            "ba27577432f81e415f1c01cc4cfabab6070e3ac50fd468fffe195ef19c0e9464"
        );
    }

    /// The parity check the Steward's second channel exists for: the live
    /// chain verifies under what this build has compiled in — the genesis
    /// key in [`PUBLISHED_KEYS`] and the roots in [`ROOT_KEYS`] — and the
    /// key the platform serves is the one that walk ends on.
    ///
    /// Before the first rotation that is the genesis key itself; after it,
    /// a key this crate has never heard of and does not need to, because
    /// the root certified it. A served key the roots did not certify, or a
    /// chain that no longer verifies, fails here within the hour.
    ///
    /// Networked, so it is `#[ignore]`d and CI runs it as its own job —
    /// a 5G blip should not read as a code failure. `just
    /// check-published-keys`.
    #[cfg(feature = "agora-client")]
    #[tokio::test]
    #[ignore = "networked: hits the live platform"]
    async fn the_published_key_is_the_one_the_platform_serves() {
        let client = crate::client::Client::new(
            url::Url::parse("https://subliminal.technology").unwrap(),
        )
        .unwrap();
        let served = client.get_governance_signing_key().await.unwrap();
        assert_eq!(served.algorithm, "ed25519");

        let genesis: PublicKeyHex = PUBLISHED_KEYS
            .first()
            .expect("PUBLISHED_KEYS is never empty")
            .parse()
            .unwrap();
        let links = client.get_governance_chain().await.unwrap();
        let report = verify_chain(
            &links,
            &genesis.to_verifying_key().unwrap(),
            &KeyAnchor::published(),
            &RootSet::published(),
        );
        let problems: Vec<_> = report
            .entries
            .iter()
            .filter_map(|e| {
                e.problem.as_ref().map(|p| (e.id.clone(), p.clone()))
            })
            .collect();
        assert!(
            report.ok,
            "the live chain does not verify under this build's genesis key \
             and roots: {problems:#?}"
        );
        assert!(report.unanchored_keys.is_empty(), "{report:#?}");
        assert_eq!(
            served.public_key, report.public_key,
            "the platform serves {} but the chain, followed under the \
             published roots, is held by {}",
            served.public_key, report.public_key
        );
    }

    #[cfg(feature = "schemars")]
    #[test]
    fn wire_schemas_are_ref_free() {
        use crate::responses::inline_schema_for;
        for (name, schema) in [
            (
                "GovernanceAttestation",
                inline_schema_for::<GovernanceAttestation>(),
            ),
            (
                "GovernanceChainLink",
                inline_schema_for::<GovernanceChainLink>(),
            ),
            (
                "GovernanceSigningKey",
                inline_schema_for::<GovernanceSigningKey>(),
            ),
            (
                "GovernanceVerification",
                inline_schema_for::<GovernanceVerification>(),
            ),
            (
                "Vec<GovernanceChainLink>",
                inline_schema_for::<Vec<GovernanceChainLink>>(),
            ),
            ("Amendment", inline_schema_for::<Amendment>()),
            ("Redaction", inline_schema_for::<Redaction>()),
            ("Revision", inline_schema_for::<Revision>()),
            ("AmendmentNotice", inline_schema_for::<AmendmentNotice>()),
            ("KeyRotation", inline_schema_for::<KeyRotation>()),
            ("TrustedHead", inline_schema_for::<TrustedHead>()),
            (
                "GovernanceKeyRecord",
                inline_schema_for::<GovernanceKeyRecord>(),
            ),
            (
                "GovernanceSigningKeys",
                inline_schema_for::<GovernanceSigningKeys>(),
            ),
            ("AmendmentKind", inline_schema_for::<AmendmentKind>()),
            ("Standing", inline_schema_for::<Standing>()),
            ("KeyStatus", inline_schema_for::<KeyStatus>()),
            ("RotationReason", inline_schema_for::<RotationReason>()),
        ] {
            let text = serde_json::to_string(&schema).unwrap();
            assert!(!text.contains("$ref"), "{name} must be $ref-free: {text}");
            assert!(
                !text.contains("$defs"),
                "{name} must be $defs-free: {text}"
            );
        }
        let text =
            serde_json::to_string(&inline_schema_for::<Sha256Hex>()).unwrap();
        assert!(text.contains("^[0-9a-f]{64}$"), "{text}");
        let text = serde_json::to_string(&inline_schema_for::<SignatureHex>())
            .unwrap();
        assert!(text.contains("^[0-9a-f]{128}$"), "{text}");
    }
}