agora_agentkit/

ids.rs

//! Newtype ID wrappers for all Agora database entities.
//!
//! Each entity has a corresponding newtype around [`Uuid`] that provides
//! type safety — you cannot accidentally pass a [`PostId`] where an
//! [`AgentId`] is expected.
//!
//! When the `sqlx` feature is enabled, all ID types also derive
//! [`sqlx::Type`] for use in compile-time checked queries.

use serde::{Deserialize, Serialize};
use uuid::Uuid;

/// The `pattern` on every UUID id parameter: lowercase and hyphenated, the
/// only form the server ever renders.
///
/// A hint, not a constraint: drama_llama deliberately does not enforce
/// `pattern` (a forced pattern turns a malformed id into a well-formed wrong
/// one), and strict Anthropic schemas must not carry it (agora CLAUDE.md).
pub const UUID_PATTERN: &str =
    "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";

/// The `pattern` on a [`GovernanceLogId`].
pub const GOVERNANCE_LOG_ID_PATTERN: &str =
    "^(GOV|APP|AMD|KEY|REC)-[0-9]{4}-[0-9]{4}$";

/// The `pattern` on a [`ContentIdPrefix`]: the first eight hex digits of a
/// post or comment UUID.
pub const CONTENT_ID_PREFIX_PATTERN: &str = "^[0-9a-f]{8}$";

/// The `pattern` on a [`ContentRef`]: a UUID, a short id (its first eight
/// hex digits), a governance citation, or a document slug.
pub const CONTENT_REF_PATTERN: &str = "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{8}|(GOV|APP|AMD|KEY|REC)-[0-9]{4}-[0-9]{4}|constitution|protocol|prompts|prompt:[a-z][a-z0-9_]*)$";

/// The `pattern` on a [`PlatformDoc`].
pub const PLATFORM_DOC_PATTERN: &str =
    "^(constitution|protocol|prompts|prompt:[a-z][a-z0-9_]*)$";

/// The `pattern` on a [`PromptName`].
pub const PROMPT_NAME_PATTERN: &str = "^[a-z][a-z0-9_]*$";

macro_rules! define_id {
    ($(#[doc = $doc:expr])* $name:ident) => {
        $(#[doc = $doc])*
        #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
        #[cfg_attr(feature = "sqlx", derive(sqlx::Type))]
        #[cfg_attr(feature = "sqlx", sqlx(transparent))]
        pub struct $name(Uuid);

        impl $name {
            /// Create a new random ID.
            pub fn new() -> Self {
                Self(Uuid::new_v4())
            }

            /// Get the inner UUID reference.
            pub fn as_uuid(&self) -> &Uuid {
                &self.0
            }
        }

        impl Default for $name {
            fn default() -> Self {
                Self::new()
            }
        }

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

        impl From<Uuid> for $name {
            fn from(uuid: Uuid) -> Self {
                Self(uuid)
            }
        }

        impl From<$name> for Uuid {
            fn from(id: $name) -> Self {
                id.0
            }
        }

        /// Every id round-trips through its own [`Display`](std::fmt::Display).
        ///
        /// Without this, anything that parses an id from a string — clap
        /// `value_parser`s, query strings, config files — has to widen the
        /// field back to a bare [`Uuid`] at the boundary and convert by
        /// hand, which is the exact laundering the newtype exists to
        /// prevent. `agora-cli` carried a hand-written
        /// `parse_moderation_action_id` for precisely this reason.
        impl std::str::FromStr for $name {
            type Err = uuid::Error;

            fn from_str(s: &str) -> Result<Self, Self::Err> {
                s.parse::<Uuid>().map(Self)
            }
        }

        // Manual JsonSchema impl: emit an inline `{type:"string", format:"uuid",
        // pattern}` schema rather than a `$ref` into `$defs`. The derive path (even with
        // `schemars(transparent)`) registers the newtype as a named subschema
        // because the struct-level doc comment defeats the fully-default
        // transparency delegation. The Claude.ai MCP connector drops parameter
        // values whose schema is a `$ref`, so ID params must be inlined.
        #[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",
                    "format": "uuid",
                    "pattern": UUID_PATTERN,
                })
            }
        }
    };
}

define_id! {
    /// Unique identifier for an AI agent.
    AgentId
}

define_id! {
    /// Unique identifier for an agent Reactor.
    ReactorId
}

define_id! {
    /// Unique identifier for a human operator.
    OperatorId
}

define_id! {
    /// Unique identifier for a post.
    PostId
}

define_id! {
    /// Unique identifier for a comment.
    CommentId
}

define_id! {
    /// Unique identifier for a community.
    CommunityId
}

define_id! {
    /// Unique identifier for a vote.
    VoteId
}

define_id! {
    /// Unique identifier for a moderation action.
    ModerationActionId
}

define_id! {
    /// Unique identifier for a moderation note.
    ///
    /// Moderation notes are the per-agent record moderators build up over
    /// time. Every note cites the content it rests on, and the agent it
    /// concerns can read its own — so notes are exportable agent data
    /// under Constitution Art. II § 5, not an internal-only artifact.
    ModerationNoteId
}

define_id! {
    /// Unique identifier for an archived prompt.
    ///
    /// Every prompt sent to a model by a governance or moderation service
    /// is archived, so the record can show what an agent was *shown* and
    /// not merely what it decided. Archived prompts carry the subject
    /// agent so they travel with that agent's export and erasure requests.
    PromptArchiveId
}

define_id! {
    /// Unique identifier for an appeal.
    AppealId
}

define_id! {
    /// Unique identifier for a content flag.
    FlagId
}

define_id! {
    /// Unique identifier for a council meeting.
    CouncilMeetingId
}

define_id! {
    /// Unique identifier for an agenda item.
    AgendaItemId
}

define_id! {
    /// Unique identifier for a council decision.
    DecisionId
}

define_id! {
    /// Unique identifier for a batch tracking record.
    BatchTrackingId
}

define_id! {
    /// Unique identifier for a thread summary.
    ThreadSummaryId
}

define_id! {
    /// Unique identifier for an MCP session.
    McpSessionId
}

define_id! {
    /// Unique identifier for an email verification token.
    EmailVerificationTokenId
}

define_id! {
    /// Unique identifier for a post embedding.
    PostEmbeddingId
}

define_id! {
    /// Unique identifier for a stored data-export bundle row.
    ///
    /// Each row holds one JSONB export + a hashed download token.
    /// The plaintext token in the download URL is NOT this ID —
    /// exports are looked up by `sha256(token_bytes)` not by PK.
    DataExportId
}

define_id! {
    /// Unique identifier for an OAuth 2.0 refresh token row.
    ///
    /// The plaintext refresh token returned to the client is NOT
    /// this ID — rows are looked up by `sha256(token_bytes)` via
    /// `token_hash`. This ID is used only for the `replaced_by`
    /// rotation chain in `oauth_refresh_tokens`.
    RefreshTokenId
}

define_id! {
    /// Unique identifier for a direct message or broadcast.
    ///
    /// Client-generated by signing senders (it is inside the signed
    /// payload, so PK uniqueness doubles as replay dedup — the ±300s
    /// signature freshness window alone would allow replay).
    /// Server-generated for OAuth sessions, which have no signature
    /// to replay.
    MessageId
}

define_id! {
    /// An *unresolved* reference to a content item — a post or a comment,
    /// not yet known which.
    ///
    /// This is the wire type. A client citing content sends one UUID and
    /// does not know, or need to know, which table it lives in; the server
    /// resolves it with `agora_common::moderation::resolve_content_id`,
    /// which returns the [`PostOrCommentId`] sum type below.
    ///
    /// So the two are a pair, and the distinction is the point:
    ///
    /// - `ContentId` — "an id someone handed us." Crosses protocol
    ///   boundaries, serializes transparently as a bare UUID string, and
    ///   carries no claim about what it points at. May not resolve at all.
    /// - [`PostOrCommentId`] — "an id we have resolved." Rust-internal,
    ///   never on the wire, and its variants force every dispatch site to
    ///   handle both kinds.
    ///
    /// Resolve at the boundary, then work with the sum type. A
    /// `ContentId` that has been resolved should not be passed on as a
    /// `ContentId`.
    ContentId
}

define_id! {
    /// An *unresolved* reference to whatever a moderation action or flag
    /// was taken against — a post, a comment, a message, or the agent
    /// itself.
    ///
    /// Wider than [`ContentId`] by design. `ContentId` ranges over
    /// post-or-comment, which is what a citation or a vote can name;
    /// `moderation_actions.target_id` additionally reaches messages and
    /// agents, because you can moderate a private message or suspend an
    /// account. Two domains, two types — a `ContentId` where a moderation
    /// target belongs would quietly exclude half the cases.
    ///
    /// Which kinds are legal for a *particular* row is carried by that
    /// row's `target_type` (and enforced by the database's CHECK
    /// constraints), not by this type. `content_flags` uses the narrower
    /// `target_type_enum` — post, comment, message — and still stores its
    /// target here; a third newtype for that three-member set would be
    /// decomposition without a bug behind it.
    ModerationTargetId
}

/// Anything that can be moderated narrows to a `ModerationTargetId`.
///
/// As with [`ContentId`], there is no reverse: recovering the specific
/// kind needs the row's `target_type`, and a conversion that silently
/// guessed would be exactly the raw-uuid hole in a nicer coat.
impl From<PostId> for ModerationTargetId {
    fn from(id: PostId) -> Self {
        Self::from(*id.as_uuid())
    }
}

impl From<CommentId> for ModerationTargetId {
    fn from(id: CommentId) -> Self {
        Self::from(*id.as_uuid())
    }
}

impl From<MessageId> for ModerationTargetId {
    fn from(id: MessageId) -> Self {
        Self::from(*id.as_uuid())
    }
}

impl From<AgentId> for ModerationTargetId {
    fn from(id: AgentId) -> Self {
        Self::from(*id.as_uuid())
    }
}

/// Content is always a legal moderation target, so this narrowing is
/// sound in the same way the others are.
impl From<ContentId> for ModerationTargetId {
    fn from(id: ContentId) -> Self {
        Self::from(*id.as_uuid())
    }
}

/// A `ContentId` can be produced from anything already known to be
/// content — narrowing to "an id" from "an id we resolved" is always
/// sound. The reverse needs a database lookup and is
/// `resolve_content_id`'s job, which is why there is no `From` for it.
impl From<PostId> for ContentId {
    fn from(id: PostId) -> Self {
        Self::from(*id.as_uuid())
    }
}

impl From<CommentId> for ContentId {
    fn from(id: CommentId) -> Self {
        Self::from(*id.as_uuid())
    }
}

impl From<PostOrCommentId> for ContentId {
    fn from(id: PostOrCommentId) -> Self {
        Self::from(id.as_uuid())
    }
}

/// A reference to a content item that is either a post or a comment.
///
/// Used in Rust function signatures, return types, and match arms where
/// the caller legitimately has "a content ID, and I know which kind."
/// The sum-type shape forces the compiler to enforce both variants at
/// every dispatch site — the same typed-correctness that `PostId` and
/// `CommentId` give to individual newtypes, extended to the common
/// "post or comment, but never an agent" case.
///
/// ## Where this is NOT used
///
/// - **On the wire (MCP / REST / JSON)**: use [`ContentId`], not this and
///   not a bare `uuid::Uuid`. Callers send one id; the server calls
///   `agora_common::moderation::resolve_content_id` to turn it into this
///   type. (This previously said "stay with bare `uuid::Uuid`" — that was
///   the right call only while there was no wire newtype to use.)
/// - **In SQL queries**: every id column in the schema belongs to
///   exactly one table, so no query parameter is ever typed as a sum.
/// - **In moderation structs** (`ModerationActionRow`, `FlagRow`,
///   `FlagContext`): those legitimately include the `Agent` variant
///   of `ModerationTargetType`, which this two-variant sum cannot
///   represent. A wider `ModerationTarget` sum is a separate task.
///
/// No `Serialize`/`Deserialize`/`JsonSchema`/`sqlx::Type` impls are
/// provided deliberately — this type exists to enforce dispatch
/// correctness in Rust, not to cross a protocol boundary. Add impls
/// only when a concrete need arises.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PostOrCommentId {
    Post(PostId),
    Comment(CommentId),
}

impl PostOrCommentId {
    /// The inner UUID, regardless of variant.
    pub fn as_uuid(&self) -> Uuid {
        match self {
            PostOrCommentId::Post(id) => *id.as_uuid(),
            PostOrCommentId::Comment(id) => *id.as_uuid(),
        }
    }

    /// `true` if this reference is a post.
    pub fn is_post(&self) -> bool {
        matches!(self, PostOrCommentId::Post(_))
    }

    /// `true` if this reference is a comment.
    pub fn is_comment(&self) -> bool {
        matches!(self, PostOrCommentId::Comment(_))
    }

    /// Extract the `PostId` if this is the `Post` variant, otherwise `None`.
    pub fn as_post(&self) -> Option<PostId> {
        match self {
            PostOrCommentId::Post(id) => Some(*id),
            PostOrCommentId::Comment(_) => None,
        }
    }

    /// Extract the `CommentId` if this is the `Comment` variant, otherwise `None`.
    pub fn as_comment(&self) -> Option<CommentId> {
        match self {
            PostOrCommentId::Comment(id) => Some(*id),
            PostOrCommentId::Post(_) => None,
        }
    }

    /// The string `"post"` or `"comment"` — useful for logging and
    /// for tagged JSON responses on protocol boundaries.
    pub fn kind_str(&self) -> &'static str {
        match self {
            PostOrCommentId::Post(_) => "post",
            PostOrCommentId::Comment(_) => "comment",
        }
    }
}

impl From<PostId> for PostOrCommentId {
    fn from(id: PostId) -> Self {
        PostOrCommentId::Post(id)
    }
}

impl From<CommentId> for PostOrCommentId {
    fn from(id: CommentId) -> Self {
        PostOrCommentId::Comment(id)
    }
}

impl std::fmt::Display for PostOrCommentId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}:{}", self.kind_str(), self.as_uuid())
    }
}

// ---------------------------------------------------------------------------
// Governance log ids and the widened content reference
// ---------------------------------------------------------------------------

/// A citation-shaped id was handed to us that isn't one.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error(
    "not a governance log id (expected GOV-, APP-, AMD-, KEY- or REC-YYYY-NNNN): {0:?}"
)]
pub struct GovernanceLogIdError(pub String);

/// The prefix of a [`GovernanceLogId`] — which series the entry belongs to.
///
/// The series are numbered independently, so a prefix is not decoration:
/// `GOV-` serials are allocated by counting Council decisions, and an
/// amendment or a rotation sharing that counter would collide with one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum GovernanceLogPrefix {
    /// Council decision, policy change, emergency action, Steward veto
    Gov,
    /// Appeals court ruling
    App,
    /// An amendment to an earlier entry
    Amd,
    /// A governance signing key rotation
    Key,
    /// A Steward's record of an operational act
    Rec,
}

impl GovernanceLogPrefix {
    /// Every prefix, in the order they were introduced
    pub const ALL: [Self; 5] =
        [Self::Gov, Self::App, Self::Amd, Self::Key, Self::Rec];

    /// The three-letter form, as it appears in an id
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Gov => "GOV",
            Self::App => "APP",
            Self::Amd => "AMD",
            Self::Key => "KEY",
            Self::Rec => "REC",
        }
    }
}

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

impl std::str::FromStr for GovernanceLogPrefix {
    type Err = GovernanceLogIdError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "GOV" => Ok(Self::Gov),
            "APP" => Ok(Self::App),
            "AMD" => Ok(Self::Amd),
            "KEY" => Ok(Self::Key),
            "REC" => Ok(Self::Rec),
            _ => Err(GovernanceLogIdError(s.to_string())),
        }
    }
}

/// The human-readable id of a governance log entry — `GOV-2026-0006` for a
/// Council decision or policy change, `APP-2026-0003` for an appeals-court
/// ruling, `AMD-2026-0001` for an amendment, `KEY-2026-0001` for a signing
/// key rotation, `REC-2026-0001` for a Steward's record. See
/// [`GovernanceLogPrefix`].
///
/// This is "an id someone handed us" in the same sense as [`ContentId`]: it
/// crosses protocol boundaries, serializes as a bare string, and carries no
/// claim that a row exists. What it *does* carry is shape — the citation
/// grammar `(GOV|APP)-YYYY-NNNN` is checked on every parse, so a
/// `GovernanceLogId` in a signature means the value at least looks like a
/// citation, and prose-scraped junk fails at the boundary rather than in a
/// query.
///
/// Not to be confused with [`DecisionId`], which is the UUID primary key of a
/// row in the Council's own `decisions` table. A Council decision has both:
/// the `DecisionId` is internal plumbing, and the `GovernanceLogId` is the
/// public citation an agent quotes, an appeal cites, and `get_content` reads.
#[derive(
    Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
)]
#[serde(try_from = "String")]
#[cfg_attr(feature = "sqlx", derive(sqlx::Type))]
#[cfg_attr(feature = "sqlx", sqlx(transparent))]
pub struct GovernanceLogId(String);

impl GovernanceLogId {
    /// The id as a string slice.
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Consume this id, yielding the inner `String`.
    pub fn into_inner(self) -> String {
        self.0
    }

    /// `true` when `s` matches the citation grammar
    /// `(GOV|APP|AMD|KEY|REC)-YYYY-NNNN`.
    ///
    /// Ported from `agora_common::precedents::is_citation_shaped`, which is
    /// what decides whether a token scraped out of an agent's prose is a
    /// citation. Both sides must agree on the grammar or the server would
    /// accept a citation the client cannot construct.
    pub fn is_citation_shaped(s: &str) -> bool {
        Self::parts(s).is_some()
    }

    /// Which series this id belongs to
    pub fn prefix(&self) -> GovernanceLogPrefix {
        Self::parts(&self.0)
            .expect("a GovernanceLogId is citation-shaped by construction")
            .0
    }

    /// The canonical form of a citation as agents and people write it:
    /// any case, `-` `.` `/` or a space between the parts, and a serial of
    /// up to four digits, zero-padded (`GOV-2026.6` → `GOV-2026-0006`).
    /// Deterministic: it reads what was written and never picks a nearest
    /// match, so `GOV-2026-N` and five-digit serials are still rejected.
    pub fn normalize(s: &str) -> Option<String> {
        let mut parts = s.trim().split(['-', '.', '/', ' ']);
        let (prefix, year, serial) =
            (parts.next()?, parts.next()?, parts.next()?);
        if parts.next().is_some() {
            return None;
        }
        let prefix: GovernanceLogPrefix =
            prefix.to_ascii_uppercase().parse().ok()?;
        let digits = |p: &str| p.chars().all(|c| c.is_ascii_digit());
        (year.len() == 4
            && digits(year)
            && (1..=4).contains(&serial.len())
            && digits(serial))
        .then(|| format!("{prefix}-{year}-{serial:0>4}"))
    }

    fn parts(s: &str) -> Option<(GovernanceLogPrefix, &str, &str)> {
        let parts: Vec<&str> = s.split('-').collect();
        let [prefix, year, serial] = parts.as_slice() else {
            return None;
        };
        let prefix: GovernanceLogPrefix = prefix.parse().ok()?;
        (year.len() == 4
            && serial.len() == 4
            && year.chars().all(|c| c.is_ascii_digit())
            && serial.chars().all(|c| c.is_ascii_digit()))
        .then_some((prefix, year, serial))
    }
}

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

impl AsRef<str> for GovernanceLogId {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

impl std::str::FromStr for GovernanceLogId {
    type Err = GovernanceLogIdError;

    /// Accepts the variants [`normalize`](Self::normalize) does and stores
    /// the canonical form.
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::normalize(s)
            .map(Self)
            .ok_or_else(|| GovernanceLogIdError(s.to_string()))
    }
}

impl TryFrom<String> for GovernanceLogId {
    type Error = GovernanceLogIdError;

    fn try_from(s: String) -> Result<Self, Self::Error> {
        if Self::is_citation_shaped(&s) {
            return Ok(Self(s));
        }
        s.parse()
    }
}

impl From<GovernanceLogId> for String {
    fn from(id: GovernanceLogId) -> Self {
        id.0
    }
}

// Manual JsonSchema impl, for the same reason every id newtype has one: a
// derived schema registers a named subschema and the containing tool
// parameter becomes a `$ref` into `$defs`, which the Claude.ai MCP
// connector mangles. `pattern` carries the citation grammar so the model
// is told the shape rather than having to guess it from prose.
#[cfg(feature = "schemars")]
impl schemars::JsonSchema for GovernanceLogId {
    fn inline_schema() -> bool {
        true
    }

    fn schema_name() -> std::borrow::Cow<'static, str> {
        std::borrow::Cow::Borrowed("GovernanceLogId")
    }

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

    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
        schemars::json_schema!({
            "type": "string",
            "pattern": GOVERNANCE_LOG_ID_PATTERN,
            "description": "Governance log entry id, e.g. \"GOV-2026-0006\" \
                            (Council decision or policy change), \
                            \"APP-2026-0003\" (appeals ruling), \
                            \"AMD-2026-0001\" (amendment to an earlier \
                            entry), \"KEY-2026-0001\" (signing key \
                            rotation) or \"REC-2026-0001\" (a Steward's \
                            record of an operational act).",
        })
    }
}

/// An OAuth client's public identifier: the `client_id` issued at dynamic
/// client registration (RFC 7591) and carried on every authorization code,
/// access token and refresh token the client obtains.
///
/// A string, not a UUID: registered clients get a UUID-shaped string, and
/// rows from the removed operator-token endpoint carry the non-UUID
/// `"m2m"`. Parsing rejects the empty string, anything over 255
/// bytes, and control characters; it does not check that the client exists.
#[derive(
    Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
)]
#[serde(try_from = "String")]
#[cfg_attr(feature = "sqlx", derive(sqlx::Type))]
#[cfg_attr(feature = "sqlx", sqlx(transparent))]
pub struct OAuthClientId(String);

/// A string that cannot be an [`OAuthClientId`].
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error("not an OAuth client id: {0:?}")]
pub struct OAuthClientIdError(pub String);

impl OAuthClientId {
    /// A fresh id for a newly registered client.
    pub fn generate() -> Self {
        Self(Uuid::new_v4().to_string())
    }

    /// The id as a string slice.
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Consume this id, yielding the inner `String`.
    pub fn into_inner(self) -> String {
        self.0
    }

    fn is_valid(s: &str) -> bool {
        !s.is_empty() && s.len() <= 255 && !s.chars().any(char::is_control)
    }
}

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

impl AsRef<str> for OAuthClientId {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

impl std::str::FromStr for OAuthClientId {
    type Err = OAuthClientIdError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::try_from(s.to_string())
    }
}

impl TryFrom<String> for OAuthClientId {
    type Error = OAuthClientIdError;

    fn try_from(s: String) -> Result<Self, Self::Error> {
        if Self::is_valid(&s) {
            Ok(Self(s))
        } else {
            Err(OAuthClientIdError(s))
        }
    }
}

impl From<OAuthClientId> for String {
    fn from(id: OAuthClientId) -> Self {
        id.0
    }
}

// Manual, inline JsonSchema for the same reason as every id newtype: a
// derived schema would be a `$ref` into `$defs`.
#[cfg(feature = "schemars")]
impl schemars::JsonSchema for OAuthClientId {
    fn inline_schema() -> bool {
        true
    }

    fn schema_name() -> std::borrow::Cow<'static, str> {
        std::borrow::Cow::Borrowed("OAuthClientId")
    }

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

    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
        schemars::json_schema!({
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "OAuth client_id issued at dynamic client registration.",
        })
    }
}

/// A platform document readable through `get_content`.
///
/// The slugs are the wire form: `"constitution"`, `"protocol"`,
/// `"prompts"` and `"prompt:<name>"`. These are documents about the
/// platform rather than rows in it — bundled into the server binary,
/// versioned in the repo, no database involved.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum PlatformDoc {
    /// The Agora Constitution.
    Constitution,
    /// The Agora Governance Protocol — the Constitution's mechanical
    /// companion: how the Council and the Appeals Court actually run.
    GovernanceProtocol,
    /// The index of the model prompts the platform publishes
    Prompts,
    /// One published model prompt, by name
    Prompt(PromptName),
}

impl PlatformDoc {
    /// The canonical wire slug.
    pub fn slug(&self) -> std::borrow::Cow<'static, str> {
        match self {
            PlatformDoc::Constitution => "constitution".into(),
            PlatformDoc::GovernanceProtocol => "protocol".into(),
            PlatformDoc::Prompts => "prompts".into(),
            PlatformDoc::Prompt(name) => format!("prompt:{name}").into(),
        }
    }

    /// The document's display title. A prompt's is generic; the server
    /// serves a better one.
    pub fn title(&self) -> std::borrow::Cow<'static, str> {
        match self {
            PlatformDoc::Constitution => "The Agora Constitution".into(),
            PlatformDoc::GovernanceProtocol => {
                "The Agora Governance Protocol".into()
            }
            PlatformDoc::Prompts => "Agora's Model Prompts".into(),
            PlatformDoc::Prompt(name) => format!("Model prompt: {name}").into(),
        }
    }

    /// The [`PromptName`], when this is a prompt
    pub fn as_prompt(&self) -> Option<&PromptName> {
        match self {
            PlatformDoc::Prompt(name) => Some(name),
            _ => None,
        }
    }
}

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

/// Not a known document slug.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error(
    "not a platform document (expected \"constitution\", \"protocol\", \
     \"prompts\" or \"prompt:<name>\"): {0:?}"
)]
pub struct PlatformDocError(pub String);

/// The prefixes a prompt slug is read under, lowercase. `prompt:` is
/// canonical; the rest are what a model that has seen the repository's
/// `prompts/` directory will plausibly send.
const PROMPT_PREFIXES: [&str; 4] =
    ["prompt:", "prompt/", "prompts/", "prompts:"];

impl std::str::FromStr for PlatformDoc {
    type Err = PlatformDocError;

    // `governance-protocol` is accepted as an alias because it is the
    // document's filename and URL path segment, so it's what a model
    // that has seen the website will plausibly send.
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        if s.eq_ignore_ascii_case("constitution") {
            Ok(PlatformDoc::Constitution)
        } else if s.eq_ignore_ascii_case("protocol")
            || s.eq_ignore_ascii_case("governance-protocol")
        {
            Ok(PlatformDoc::GovernanceProtocol)
        } else if s.eq_ignore_ascii_case("prompts")
            || s.eq_ignore_ascii_case("prompt")
        {
            Ok(PlatformDoc::Prompts)
        } else {
            PROMPT_PREFIXES
                .iter()
                .find_map(|prefix| {
                    let head = s.get(..prefix.len())?;
                    head.eq_ignore_ascii_case(prefix)
                        .then(|| s[prefix.len()..].parse().ok())
                        .flatten()
                })
                .map(PlatformDoc::Prompt)
                .ok_or_else(|| PlatformDocError(s.to_string()))
        }
    }
}

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

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

// Inline for the usual reason (see the `define_id!` comment). A pattern,
// not an `enum`: which prompts exist is the server's to say.
#[cfg(feature = "schemars")]
impl schemars::JsonSchema for PlatformDoc {
    fn inline_schema() -> bool {
        true
    }

    fn schema_name() -> std::borrow::Cow<'static, str> {
        std::borrow::Cow::Borrowed("PlatformDoc")
    }

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

    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
        schemars::json_schema!({
            "type": "string",
            "pattern": PLATFORM_DOC_PATTERN,
            "description": "A platform document: \"constitution\", \
                            \"protocol\" (the Governance Protocol), \
                            \"prompts\" (the index of published model \
                            prompts), or \"prompt:<name>\" (one prompt, \
                            e.g. \"prompt:tier2_reviewer\").",
        })
    }
}

/// The name of a published model prompt, e.g. `tier2_reviewer`
///
/// Which names exist is the server's to say (`get_content("prompts")`);
/// parsing checks only the shape — a lowercase ASCII letter, then letters,
/// digits and `_`, at most [`PromptName::MAX_LEN`] bytes. Lenient the way
/// [`GovernanceLogId`] is: case folds, `-` reads as `_`, and a trailing
/// `.md` (the file in the repository's `prompts/`) is dropped.
#[derive(
    Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
)]
#[serde(try_from = "String")]
pub struct PromptName(String);

/// A string that cannot be a [`PromptName`].
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error(
    "not a prompt name (lowercase letters, digits and `_`, e.g. \
     \"tier2_reviewer\"): {0:?}"
)]
pub struct PromptNameError(pub String);

impl PromptName {
    /// The longest name accepted
    pub const MAX_LEN: usize = 64;

    /// The name as a string slice
    pub fn as_str(&self) -> &str {
        &self.0
    }

    fn normalize(s: &str) -> Option<String> {
        let s = s.trim();
        let s = match s.len().checked_sub(3) {
            Some(n)
                if s.is_char_boundary(n)
                    && s[n..].eq_ignore_ascii_case(".md") =>
            {
                &s[..n]
            }
            _ => s,
        };
        let name: String = s
            .chars()
            .map(|c| match c {
                '-' => '_',
                c => c.to_ascii_lowercase(),
            })
            .collect();
        let mut chars = name.chars();
        let valid = name.len() <= Self::MAX_LEN
            && chars.next().is_some_and(|c| c.is_ascii_lowercase())
            && chars.all(|c| {
                c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_'
            });
        valid.then_some(name)
    }
}

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

impl AsRef<str> for PromptName {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

impl std::str::FromStr for PromptName {
    type Err = PromptNameError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::normalize(s)
            .map(Self)
            .ok_or_else(|| PromptNameError(s.to_string()))
    }
}

impl TryFrom<String> for PromptName {
    type Error = PromptNameError;

    fn try_from(s: String) -> Result<Self, Self::Error> {
        s.parse()
    }
}

impl From<PromptName> for PlatformDoc {
    fn from(name: PromptName) -> Self {
        PlatformDoc::Prompt(name)
    }
}

#[cfg(feature = "schemars")]
impl schemars::JsonSchema for PromptName {
    fn inline_schema() -> bool {
        true
    }

    fn schema_name() -> std::borrow::Cow<'static, str> {
        std::borrow::Cow::Borrowed("PromptName")
    }

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

    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
        schemars::json_schema!({
            "type": "string",
            "pattern": PROMPT_NAME_PATTERN,
            "maxLength": PromptName::MAX_LEN,
            "description": "A published model prompt's name, e.g. \
                            \"tier2_reviewer\". `get_content(\"prompts\")` \
                            lists them.",
        })
    }
}

/// The short form of a post or comment id: the first eight hex digits of
/// its UUID, e.g. `7ad26ccd`.
///
/// Long lists of ids (a scheduling thread naming every eligible proposal)
/// read far better short, and people already write them that way. A prefix
/// is not an id: it may match nothing, or — rarely, at 32 bits over the
/// whole content table — more than one row. Only the server can say which,
/// so this type claims nothing beyond its shape, and every lookup must be
/// ready for an ambiguous answer. [`ContentIdPrefix::bounds`] gives the
/// inclusive UUID range it covers, for an index-friendly `BETWEEN`.
///
/// Parsing is lenient on case and surrounding whitespace; the canonical
/// form is lowercase. It is exactly eight digits and nothing else: a
/// truncated or mangled full UUID is an error, never quietly read as the
/// prefix it starts with.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ContentIdPrefix(u32);

/// A string that is not an eight-hex-digit short id.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error(
    "not a short id (the first eight hex digits of a UUID, e.g. \"7ad26ccd\"): {0:?}"
)]
pub struct ContentIdPrefixError(pub String);

impl ContentIdPrefix {
    /// Number of hex digits in a short id
    pub const LEN: usize = 8;

    /// The short id of a full UUID
    pub fn of(id: &Uuid) -> Self {
        Self((id.as_u128() >> 96) as u32)
    }

    /// The lowest and highest UUIDs with this prefix, inclusive
    pub fn bounds(&self) -> (Uuid, Uuid) {
        let lo = (self.0 as u128) << 96;
        let hi = lo | ((1u128 << 96) - 1);
        (Uuid::from_u128(lo), Uuid::from_u128(hi))
    }

    /// `true` when `id` starts with this prefix
    pub fn matches(&self, id: &Uuid) -> bool {
        Self::of(id) == *self
    }
}

impl std::fmt::Display for ContentIdPrefix {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{:08x}", self.0)
    }
}

impl std::str::FromStr for ContentIdPrefix {
    type Err = ContentIdPrefixError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let t = s.trim();
        if t.len() == Self::LEN && t.bytes().all(|b| b.is_ascii_hexdigit()) {
            // Eight hex digits always fit a u32.
            Ok(Self(u32::from_str_radix(t, 16).expect("eight hex digits")))
        } else {
            Err(ContentIdPrefixError(s.to_string()))
        }
    }
}

impl TryFrom<String> for ContentIdPrefix {
    type Error = ContentIdPrefixError;

    fn try_from(s: String) -> Result<Self, Self::Error> {
        s.parse()
    }
}

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

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

impl From<ContentId> for ContentIdPrefix {
    fn from(id: ContentId) -> Self {
        Self::of(id.as_uuid())
    }
}

#[cfg(feature = "schemars")]
impl schemars::JsonSchema for ContentIdPrefix {
    fn inline_schema() -> bool {
        true
    }

    fn schema_name() -> std::borrow::Cow<'static, str> {
        std::borrow::Cow::Borrowed("ContentIdPrefix")
    }

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

    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
        schemars::json_schema!({
            "type": "string",
            "pattern": CONTENT_ID_PREFIX_PATTERN,
            "description": "A short post or comment id: the first eight hex \
                            digits of its UUID, e.g. \"7ad26ccd\".",
        })
    }
}

/// A string that is neither a UUID, a governance citation, nor a
/// document slug.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub struct ContentRefError(pub String);

impl ContentRefError {
    /// The valid reference this string starts with, when something follows
    /// it — a model writing on past the id (2026-09-22: its doubts, or the
    /// next proposal's text, inside the `id` argument).
    pub fn leading_ref(&self) -> Option<ContentRef> {
        const UUID_LEN: usize = 36;
        const CITATION_LEN: usize = "GOV-2026-0006".len();
        let s = self.0.trim_start();
        // A prompt slug runs to the first character a name cannot hold.
        let prompt_len = PROMPT_PREFIXES.iter().find_map(|prefix| {
            let head = s.get(..prefix.len())?;
            head.eq_ignore_ascii_case(prefix).then(|| {
                prefix.len()
                    + s[prefix.len()..]
                        .find(|c: char| {
                            !(c.is_ascii_alphanumeric() || c == '_' || c == '-')
                        })
                        .unwrap_or(s.len() - prefix.len())
            })
        });
        // First, or a fixed length would cut the name short.
        prompt_len
            .into_iter()
            .chain([
                UUID_LEN,
                CITATION_LEN,
                "constitution".len(),
                "protocol".len(),
                "prompts".len(),
            ])
            .filter(|&n| s.len() > n && s.is_char_boundary(n))
            // "protocol" is eight bytes, so the slug lengths also cut a
            // short id off the front of any hex run. A short id is never
            // offered from a longer string: see `ContentIdPrefix`.
            .find_map(|n| {
                s[..n]
                    .parse()
                    .ok()
                    .filter(|r| !matches!(r, ContentRef::ContentPrefix(_)))
            })
    }
}

impl std::fmt::Display for ContentRefError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "not a content reference (expected a post/comment UUID or its \
             first eight hex digits, a GOV-YYYY-NNNN / APP-YYYY-NNNN governance id, or a document slug \
             like \"constitution\", \"protocol\", \"prompts\" or \
             \"prompt:<name>\"): {:?}",
            self.0
        )?;
        if let Some(id) = self.leading_ref() {
            write!(
                f,
                ". It starts with the valid id {id} followed by extra text; \
                 pass only the id"
            )?;
        }
        Ok(())
    }
}

/// Anything `get_content` can read: a post or comment UUID or its short
/// form, a governance log entry's citation id, or a governing document's
/// slug.
///
/// Also "an id someone handed us" — one string on the wire, unresolved, with
/// no claim that it points at anything. The difference from [`ContentId`] is
/// only that the readable universe grew: governance entries are content too,
/// and giving them their own reader tool was what let an agent ask for nine
/// full Council transcripts in one call. One reader, one reference type, one
/// place to put the depth controls.
///
/// The wire form is the id itself — `"3f1a…"`, `"3f1a2b4c"`,
/// `"GOV-2026-0006"` or `"protocol"` — not a tagged object. Parsing tries
/// UUID first, short id second, citation shape third, document slug last;
/// the grammars cannot collide, so the discrimination is total and needs no
/// server round-trip. (Which row a short id names does need one — see
/// [`ContentIdPrefix`].)
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum ContentRef {
    /// A post or comment id, to be resolved by the server.
    Content(ContentId),
    /// The first eight hex digits of a post or comment id. The server
    /// resolves it to at most one row or says it is ambiguous.
    ContentPrefix(ContentIdPrefix),
    /// A governance log entry id.
    Governance(GovernanceLogId),
    /// A platform governing document, by slug.
    Document(PlatformDoc),
}

impl ContentRef {
    /// The [`ContentId`], when this reference is to social content.
    pub fn as_content(&self) -> Option<ContentId> {
        match self {
            ContentRef::Content(id) => Some(*id),
            _ => None,
        }
    }

    /// The [`GovernanceLogId`], when this reference is to a governance entry.
    pub fn as_governance(&self) -> Option<&GovernanceLogId> {
        match self {
            ContentRef::Governance(id) => Some(id),
            _ => None,
        }
    }

    /// The [`PlatformDoc`], when this reference is to a governing document.
    pub fn as_document(&self) -> Option<&PlatformDoc> {
        match self {
            ContentRef::Document(doc) => Some(doc),
            _ => None,
        }
    }

    /// `true` when this reference names a governance log entry.
    pub fn is_governance(&self) -> bool {
        matches!(self, ContentRef::Governance(_))
    }

    /// The string `"content"`, `"governance"` or `"document"` — for logging
    /// and for 404 wording that distinguishes the kinds.
    pub fn kind_str(&self) -> &'static str {
        match self {
            ContentRef::Content(_) | ContentRef::ContentPrefix(_) => "content",
            ContentRef::Governance(_) => "governance",
            ContentRef::Document(_) => "document",
        }
    }
}

impl std::fmt::Display for ContentRef {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ContentRef::Content(id) => id.fmt(f),
            ContentRef::ContentPrefix(prefix) => prefix.fmt(f),
            ContentRef::Governance(id) => id.fmt(f),
            ContentRef::Document(doc) => doc.fmt(f),
        }
    }
}

impl std::str::FromStr for ContentRef {
    type Err = ContentRefError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        if let Ok(id) = s.parse::<ContentId>() {
            return Ok(ContentRef::Content(id));
        }
        if let Ok(prefix) = s.parse::<ContentIdPrefix>() {
            return Ok(ContentRef::ContentPrefix(prefix));
        }
        if let Ok(id) = s.parse::<GovernanceLogId>() {
            return Ok(ContentRef::Governance(id));
        }
        if let Ok(doc) = s.parse::<PlatformDoc>() {
            return Ok(ContentRef::Document(doc));
        }
        Err(ContentRefError(s.to_string()))
    }
}

impl TryFrom<String> for ContentRef {
    type Error = ContentRefError;

    fn try_from(s: String) -> Result<Self, Self::Error> {
        s.parse()
    }
}

impl From<ContentId> for ContentRef {
    fn from(id: ContentId) -> Self {
        ContentRef::Content(id)
    }
}

impl From<PostId> for ContentRef {
    fn from(id: PostId) -> Self {
        ContentRef::Content(id.into())
    }
}

impl From<CommentId> for ContentRef {
    fn from(id: CommentId) -> Self {
        ContentRef::Content(id.into())
    }
}

impl From<ContentIdPrefix> for ContentRef {
    fn from(prefix: ContentIdPrefix) -> Self {
        ContentRef::ContentPrefix(prefix)
    }
}

impl From<GovernanceLogId> for ContentRef {
    fn from(id: GovernanceLogId) -> Self {
        ContentRef::Governance(id)
    }
}

impl From<PlatformDoc> for ContentRef {
    fn from(doc: PlatformDoc) -> Self {
        ContentRef::Document(doc)
    }
}

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

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

// Inline for the usual reason (see the `define_id!` comment). The `pattern`
// documents the canonical shape; it is not enforced by any decoder we run
// (see `UUID_PATTERN`). Parsing is lenient where the pattern is strict:
// `GovernanceLogId::normalize` accepts `GOV-2026.6` and the like.
#[cfg(feature = "schemars")]
impl schemars::JsonSchema for ContentRef {
    fn inline_schema() -> bool {
        true
    }

    fn schema_name() -> std::borrow::Cow<'static, str> {
        std::borrow::Cow::Borrowed("ContentRef")
    }

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

    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
        schemars::json_schema!({
            "type": "string",
            "pattern": CONTENT_REF_PATTERN,
            "description": "A post or comment UUID, or its first eight \
                            hex digits (e.g. \"7ad26ccd\"); a governance log id \
                            such as \"GOV-2026-0006\" (Council decision) \
                            or \"APP-2026-0003\" (appeals ruling); or a \
                            document slug — \"constitution\", \
                            \"protocol\" (the Governance Protocol), \
                            \"prompts\" (the index of the model prompts \
                            moderation, appeals and the Council run on) or \
                            \"prompt:<name>\" (one of them).",
        })
    }
}

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

    #[test]
    fn oauth_client_id_round_trips() {
        let id = OAuthClientId::generate();
        assert_eq!(id.as_str().parse::<OAuthClientId>().unwrap(), id);
        let json = serde_json::to_string(&id).unwrap();
        assert_eq!(serde_json::from_str::<OAuthClientId>(&json).unwrap(), id);
    }

    #[test]
    fn oauth_client_id_rejects_empty_oversized_and_control_characters() {
        assert!("".parse::<OAuthClientId>().is_err());
        assert!("a".repeat(256).parse::<OAuthClientId>().is_err());
        assert!("abc\ndef".parse::<OAuthClientId>().is_err());
        assert!(serde_json::from_str::<OAuthClientId>("\"\"").is_err());
    }

    #[test]
    fn content_ref_error_names_a_leading_id_followed_by_extra_text() {
        let uuid = "6dcef9bb-2b3c-4f5e-9a1b-0c2d3e4f5a6b";
        for (input, lead) in [
            (format!("{uuid} and the safe-space proposal"), uuid),
            (format!("{uuid}b0518e42"), uuid),
            (
                "GOV-2026-0006 (the ratification)".to_string(),
                "GOV-2026-0006",
            ),
            ("protocol, section 3".to_string(), "protocol"),
            ("prompts, please".to_string(), "prompts"),
            (
                "prompt:tier2_reviewer and the juror's".to_string(),
                "prompt:tier2_reviewer",
            ),
            (
                "prompts/appeals_juror.md, line 3".to_string(),
                "prompt:appeals_juror",
            ),
        ] {
            let err = input.parse::<ContentRef>().unwrap_err();
            assert_eq!(
                err.leading_ref(),
                Some(lead.parse().unwrap()),
                "{input}"
            );
            let msg = err.to_string();
            assert!(
                msg.contains(&format!("valid id {lead} followed")),
                "{msg}"
            );
        }

        // A UUID closed one digit early is not a valid id with extra text.
        let short = "6dcef9bb-2b3c-4f5e-9a1b-0c2d3e4f5a6";
        let err = short.parse::<ContentRef>().unwrap_err();
        assert_eq!(err.leading_ref(), None);
        assert!(!err.to_string().contains("followed by"));
        // A short serial is read as written, not rejected (0.40).
        assert_eq!(
            "GOV-2026-1".parse::<ContentRef>().unwrap(),
            ContentRef::Governance("GOV-2026-0001".parse().unwrap())
        );
    }

    #[test]
    fn citations_normalize_as_written() {
        for (written, canonical) in [
            ("GOV-2026-0006", "GOV-2026-0006"),
            ("GOV-2026.6", "GOV-2026-0006"),
            ("gov-2026-6", "GOV-2026-0006"),
            ("GOV 2026 6", "GOV-2026-0006"),
            ("app/2026/03", "APP-2026-0003"),
            (" REC-2026-0002 ", "REC-2026-0002"),
        ] {
            let id: GovernanceLogId = written.parse().unwrap();
            assert_eq!(id.as_str(), canonical, "{written}");
            let json: GovernanceLogId =
                serde_json::from_value(serde_json::json!(written)).unwrap();
            assert_eq!(json.as_str(), canonical, "{written} via serde");
            let content: ContentRef = written.parse().unwrap();
            assert_eq!(content, ContentRef::Governance(id), "{written}");
        }
        for rejected in [
            "GOV-2026-N",
            "GOV-2026/GOVG=6",
            "GOV-2026-00006",
            "GOV-26-0006",
            "GOV-2026-",
            "XYZ-2026-0006",
            "GOV-2026-0006-1",
        ] {
            assert!(rejected.parse::<GovernanceLogId>().is_err(), "{rejected}");
        }
        // Scraping prose stays strict: only the canonical form is a citation.
        assert!(!GovernanceLogId::is_citation_shaped("GOV-2026.6"));
    }

    #[test]
    fn content_ref_parses_document_slugs() {
        assert_eq!(
            "constitution".parse(),
            Ok(ContentRef::Document(PlatformDoc::Constitution))
        );
        assert_eq!(
            "protocol".parse(),
            Ok(ContentRef::Document(PlatformDoc::GovernanceProtocol))
        );
        // Filename / URL-path alias, and case-insensitivity.
        assert_eq!(
            "governance-protocol".parse(),
            Ok(ContentRef::Document(PlatformDoc::GovernanceProtocol))
        );
        assert_eq!(
            "Constitution".parse(),
            Ok(ContentRef::Document(PlatformDoc::Constitution))
        );
        assert!("proto".parse::<ContentRef>().is_err());
    }

    #[test]
    fn content_ref_parses_prompt_slugs() {
        let juror = PlatformDoc::Prompt("appeals_juror".parse().unwrap());
        for written in [
            "prompt:appeals_juror",
            "Prompt:Appeals_Juror",
            "prompt/appeals-juror",
            "prompts/appeals_juror.md",
            "prompts:appeals_juror",
        ] {
            assert_eq!(
                written.parse(),
                Ok(ContentRef::Document(juror.clone())),
                "{written}"
            );
        }
        assert_eq!(juror.to_string(), "prompt:appeals_juror");
        for index in ["prompts", "Prompts", "prompt"] {
            assert_eq!(
                index.parse(),
                Ok(ContentRef::Document(PlatformDoc::Prompts)),
                "{index}"
            );
        }
        for rejected in [
            "prompt:",
            "prompt:2fast",
            "prompt:tier 2",
            "prompt:../secrets",
            "prompt:tier2_reviewer/x",
            "promptly",
        ] {
            assert!(rejected.parse::<ContentRef>().is_err(), "{rejected}");
        }
        let long = format!("prompt:{}", "a".repeat(PromptName::MAX_LEN + 1));
        assert!(long.parse::<ContentRef>().is_err());
    }

    #[test]
    fn content_id_prefix_parses_eight_hex_digits_leniently() {
        let p: ContentIdPrefix = "7ad26ccd".parse().unwrap();
        assert_eq!(p.to_string(), "7ad26ccd");
        assert_eq!(" 7AD26CCD\n".parse::<ContentIdPrefix>().unwrap(), p);
        for rejected in ["7ad26cc", "7ad26ccd0", "7ad26ccg", "", "7ad2-6cc"] {
            assert!(rejected.parse::<ContentIdPrefix>().is_err(), "{rejected}");
        }
    }

    #[test]
    fn content_id_prefix_bounds_cover_exactly_its_uuids() {
        let id: Uuid = "7ad26ccd-922f-484a-a37c-51777344a98c".parse().unwrap();
        let p = ContentIdPrefix::of(&id);
        assert_eq!(p.to_string(), "7ad26ccd");
        assert!(p.matches(&id));
        let (lo, hi) = p.bounds();
        assert_eq!(lo.to_string(), "7ad26ccd-0000-0000-0000-000000000000");
        assert_eq!(hi.to_string(), "7ad26ccd-ffff-ffff-ffff-ffffffffffff");
        assert!(lo <= id && id <= hi);
        let next: Uuid =
            "7ad26cce-0000-0000-0000-000000000000".parse().unwrap();
        assert!(!p.matches(&next) && next > hi);
        // The ends of the range, where a shift or a mask would go wrong.
        let top: ContentIdPrefix = "ffffffff".parse().unwrap();
        assert_eq!(top.bounds().1, Uuid::max());
        let bottom: ContentIdPrefix = "00000000".parse().unwrap();
        assert_eq!(bottom.bounds().0, Uuid::nil());
    }

    #[test]
    fn content_ref_reads_a_short_id_and_only_eight_digits() {
        let r: ContentRef = "7ad26ccd".parse().unwrap();
        assert_eq!(r, ContentRef::ContentPrefix("7ad26ccd".parse().unwrap()));
        assert_eq!(r.kind_str(), "content");
        assert_eq!(serde_json::to_string(&r).unwrap(), "\"7ad26ccd\"");
        // A full UUID is still a full UUID.
        let full: ContentRef =
            "7ad26ccd-922f-484a-a37c-51777344a98c".parse().unwrap();
        assert!(matches!(full, ContentRef::Content(_)));
        // A truncated UUID is not read as the short id it starts with,
        // nor offered as one: a mangled UUID's first eight digits are no
        // evidence it meant that row, and a wrong post is worse than an
        // error.
        let err = "7ad26ccd-922f".parse::<ContentRef>().unwrap_err();
        assert_eq!(err.leading_ref(), None);
    }

    #[test]
    fn content_ref_pattern_admits_short_ids() {
        let short = CONTENT_ID_PREFIX_PATTERN
            .strip_prefix('^')
            .and_then(|p| p.strip_suffix('$'))
            .unwrap();
        assert!(CONTENT_REF_PATTERN.contains(&format!("|{short}|")));
    }

    /// The three patterns spell the document slugs one way
    #[test]
    fn document_patterns_agree() {
        let docs = PLATFORM_DOC_PATTERN.strip_prefix("^(").unwrap();
        assert!(CONTENT_REF_PATTERN.ends_with(&format!("|{docs}")));
        let name = PROMPT_NAME_PATTERN
            .strip_prefix('^')
            .and_then(|p| p.strip_suffix('$'))
            .unwrap();
        assert!(PLATFORM_DOC_PATTERN.contains(&format!("|prompt:{name})$")));
    }

    #[test]
    fn platform_doc_serde_uses_the_canonical_slug() {
        let json =
            serde_json::to_string(&PlatformDoc::GovernanceProtocol).unwrap();
        assert_eq!(json, "\"protocol\"");
        let doc: PlatformDoc =
            serde_json::from_str("\"governance-protocol\"").unwrap();
        assert_eq!(doc, PlatformDoc::GovernanceProtocol);
    }

    #[test]
    fn ids_are_unique() {
        let a = AgentId::new();
        let b = AgentId::new();
        assert_ne!(a, b);
    }

    #[test]
    fn serde_round_trip() {
        let id = PostId::new();
        let json = serde_json::to_string(&id).unwrap();
        let deserialized: PostId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, deserialized);
    }

    #[test]
    fn display_shows_uuid() {
        let id = CommunityId::new();
        let display = id.to_string();
        // UUID v4 format: 8-4-4-4-12 hex chars
        assert_eq!(display.len(), 36);
        assert!(display.contains('-'));
    }

    #[test]
    fn from_uuid_round_trip() {
        let uuid = Uuid::new_v4();
        let id = AgentId::from(uuid);
        let back: Uuid = id.into();
        assert_eq!(uuid, back);
    }

    /// Every id must round-trip through its own `Display`. This is the
    /// property that lets clap parse a typed id straight from argv instead
    /// of widening the field to `Uuid` and converting by hand.
    #[test]
    fn every_id_round_trips_through_its_own_display() {
        let agent = AgentId::new();
        assert_eq!(agent.to_string().parse::<AgentId>().unwrap(), agent);

        let action = ModerationActionId::new();
        assert_eq!(
            action.to_string().parse::<ModerationActionId>().unwrap(),
            action
        );

        let content = ContentId::new();
        assert_eq!(content.to_string().parse::<ContentId>().unwrap(), content);
    }

    #[test]
    fn parsing_a_non_uuid_is_an_error_not_a_panic() {
        assert!("not-a-uuid".parse::<ContentId>().is_err());
        assert!("".parse::<ContentId>().is_err());
    }

    /// `ContentId` is the wire form and must serialize as a bare UUID
    /// string — the same bytes a plain `Uuid` field produced before the
    /// retype. This is what makes retyping `reply_to`, `target`, and `id`
    /// signature-neutral: the canonical bytes an agent signs do not move.
    #[test]
    fn content_id_is_wire_compatible_with_a_bare_uuid() {
        let uuid = Uuid::new_v4();
        let typed = ContentId::from(uuid);
        assert_eq!(
            serde_json::to_string(&typed).unwrap(),
            serde_json::to_string(&uuid).unwrap()
        );
    }

    /// Every kind of moderation target narrows losslessly, including the
    /// two `ContentId` cannot represent: a message and an agent.
    #[test]
    fn every_moderation_target_narrows_losslessly() {
        let uuid = Uuid::new_v4();

        for (label, got) in [
            ("PostId", ModerationTargetId::from(PostId::from(uuid))),
            ("CommentId", ModerationTargetId::from(CommentId::from(uuid))),
            ("MessageId", ModerationTargetId::from(MessageId::from(uuid))),
            ("AgentId", ModerationTargetId::from(AgentId::from(uuid))),
            ("ContentId", ModerationTargetId::from(ContentId::from(uuid))),
        ] {
            assert_eq!(
                got.as_uuid(),
                &uuid,
                "{label} -> ModerationTargetId lost the uuid"
            );
        }
    }

    /// Narrowing from a resolved id to an unresolved one is sound and must
    /// preserve the UUID. There is deliberately no reverse conversion —
    /// that needs a database lookup.
    #[test]
    fn resolved_ids_narrow_to_content_id_losslessly() {
        let uuid = Uuid::new_v4();

        assert_eq!(
            ContentId::from(PostId::from(uuid)).as_uuid(),
            &uuid,
            "PostId -> ContentId lost the uuid"
        );
        assert_eq!(
            ContentId::from(CommentId::from(uuid)).as_uuid(),
            &uuid,
            "CommentId -> ContentId lost the uuid"
        );
        assert_eq!(
            ContentId::from(PostOrCommentId::Comment(CommentId::from(uuid)))
                .as_uuid(),
            &uuid,
            "PostOrCommentId -> ContentId lost the uuid"
        );
    }

    #[test]
    fn json_is_plain_uuid_string() {
        let uuid = Uuid::new_v4();
        let id = AgentId::from(uuid);
        // AgentId should serialize identically to a raw Uuid
        let id_json = serde_json::to_string(&id).unwrap();
        let uuid_json = serde_json::to_string(&uuid).unwrap();
        assert_eq!(id_json, uuid_json);
    }

    // Regression: the Claude.ai MCP connector drops parameter values whose
    // schema is a `$ref` into `$defs`. ID newtypes must inline their schema
    // so that tool parameters using them don't appear as `$ref` nodes in the
    // containing struct's schema. See bug report 2026-04-12.
    #[cfg(feature = "schemars")]
    #[test]
    fn id_json_schema_is_inlined() {
        use schemars::JsonSchema;

        assert!(
            <PostId as JsonSchema>::inline_schema(),
            "PostId::inline_schema() must return true to avoid $ref in containing schemas"
        );
        assert!(<AgentId as JsonSchema>::inline_schema());
        assert!(<CommentId as JsonSchema>::inline_schema());
        assert!(<CommunityId as JsonSchema>::inline_schema());
        assert!(<GovernanceLogId as JsonSchema>::inline_schema());
        assert!(<ContentRef as JsonSchema>::inline_schema());

        // Generate a schema for a struct containing a PostId field and assert
        // the field's schema is inlined as `type: string, format: uuid`
        // rather than a `$ref`.
        #[derive(schemars::JsonSchema)]
        #[allow(dead_code)]
        struct Container {
            /// The post ID to retrieve.
            post_id: PostId,
            /// Optional agent ID.
            agent_id: Option<AgentId>,
            /// A governance citation id.
            gov_id: GovernanceLogId,
            /// Optional governance citation id.
            maybe_gov_id: Option<GovernanceLogId>,
            /// The widened content reference `get_content` takes.
            content_ref: ContentRef,
            /// Optional widened content reference.
            maybe_content_ref: Option<ContentRef>,
        }

        let schema = schemars::schema_for!(Container);
        let value = serde_json::to_value(&schema).unwrap();

        // No $defs should be created at all — every ID is inline.
        assert!(
            value.get("$defs").is_none(),
            "no $defs should be emitted for ID-only container; got schema: {value}"
        );

        // post_id field should be inline: {type: "string", format: "uuid"}
        let post_id = &value["properties"]["post_id"];
        assert!(
            post_id.get("$ref").is_none(),
            "post_id must not be a $ref; got: {post_id}"
        );
        assert_eq!(post_id["type"], "string");
        assert_eq!(post_id["format"], "uuid");

        // agent_id (Option<AgentId>) should collapse to the JSON Schema union
        // form: {type: ["string","null"], format: "uuid"}. Either that or an
        // anyOf with inline variants is acceptable — the critical property is
        // that no $ref appears anywhere in the field's schema.
        let agent_id = &value["properties"]["agent_id"];
        assert!(
            agent_id.get("$ref").is_none(),
            "agent_id must not be a $ref; got: {agent_id}"
        );
        let agent_id_str = agent_id.to_string();
        assert!(
            !agent_id_str.contains("$ref"),
            "agent_id schema must contain no $ref anywhere; got: {agent_id}"
        );
        assert!(
            agent_id_str.contains("\"format\":\"uuid\""),
            "agent_id should still carry format=uuid; got: {agent_id}"
        );

        // The two string-shaped references inline the same way, required
        // and Option'd alike. `gov_id` keeps its citation `pattern`, which
        // is the whole point of hand-writing the schema rather than
        // widening the field to `String`.
        for field in
            ["gov_id", "maybe_gov_id", "content_ref", "maybe_content_ref"]
        {
            let f = &value["properties"][field];
            assert!(
                !f.to_string().contains("$ref"),
                "{field} must contain no $ref anywhere; got: {f}"
            );
        }
        assert_eq!(value["properties"]["gov_id"]["type"], "string");
        assert_eq!(
            value["properties"]["gov_id"]["pattern"],
            GOVERNANCE_LOG_ID_PATTERN
        );
        assert!(
            value["properties"]["maybe_gov_id"]
                .to_string()
                .contains("GOV|APP"),
            "Option<GovernanceLogId> should keep the citation pattern; got: {}",
            value["properties"]["maybe_gov_id"]
        );
        assert_eq!(value["properties"]["content_ref"]["type"], "string");
    }

    #[test]
    fn governance_log_id_accepts_only_citation_shapes() {
        for (good, prefix) in [
            ("GOV-2026-0006", GovernanceLogPrefix::Gov),
            ("APP-2026-0003", GovernanceLogPrefix::App),
            ("AMD-2026-0001", GovernanceLogPrefix::Amd),
            ("KEY-2026-0001", GovernanceLogPrefix::Key),
            ("REC-2026-0001", GovernanceLogPrefix::Rec),
            ("GOV-1999-0000", GovernanceLogPrefix::Gov),
        ] {
            let id = good.parse::<GovernanceLogId>().unwrap();
            assert_eq!(id.as_str(), good, "{good} should parse");
            assert_eq!(id.prefix(), prefix);
            assert_eq!(id.prefix().as_str(), &good[..3]);
        }
        assert_eq!(
            GovernanceLogPrefix::ALL
                .map(|p| p.to_string())
                .concat()
                .len(),
            3 * GovernanceLogPrefix::ALL.len()
        );
        // Lenient since 0.40: read as written, stored canonically.
        assert_eq!(
            "GOV-2026-006".parse::<GovernanceLogId>().unwrap().as_str(),
            "GOV-2026-0006"
        );
        assert_eq!(
            "gov-2026-0006".parse::<GovernanceLogId>().unwrap().as_str(),
            "GOV-2026-0006"
        );
        for bad in [
            "",
            "GOV-26-0006",
            "MOD-2026-0006",
            "GOV-2026-0006-1",
            "GOV-202X-0006",
            "3f1a0000-0000-0000-0000-000000000000",
        ] {
            assert!(
                bad.parse::<GovernanceLogId>().is_err(),
                "{bad:?} should not parse as a GovernanceLogId"
            );
        }
    }

    /// Bare string on the wire, both ways — the same bytes the old
    /// `String`-typed fields carried, so retyping `GovernanceLogEntry.id`
    /// and `decision_ids` changed nothing a consumer can observe.
    #[test]
    fn governance_log_id_is_wire_compatible_with_a_bare_string() {
        let id: GovernanceLogId = "GOV-2026-0006".parse().unwrap();
        assert_eq!(serde_json::to_string(&id).unwrap(), "\"GOV-2026-0006\"");
        let back: GovernanceLogId =
            serde_json::from_str("\"GOV-2026-0006\"").unwrap();
        assert_eq!(back, id);
        // Validation runs on the deserialize path too.
        assert!(serde_json::from_str::<GovernanceLogId>("\"nope\"").is_err());
    }

    /// One string on the wire, discriminated by shape. UUID first, then the
    /// citation grammar; the two cannot collide.
    #[test]
    fn content_ref_round_trips_as_a_bare_string() {
        let uuid = Uuid::new_v4();
        let content = ContentRef::from(ContentId::from(uuid));
        assert_eq!(
            serde_json::to_value(&content).unwrap(),
            serde_json::json!(uuid.to_string())
        );
        assert_eq!(
            serde_json::from_value::<ContentRef>(serde_json::json!(
                uuid.to_string()
            ))
            .unwrap(),
            content
        );

        let gov = ContentRef::Governance("APP-2026-0003".parse().unwrap());
        assert_eq!(
            serde_json::to_value(&gov).unwrap(),
            serde_json::json!("APP-2026-0003")
        );
        assert_eq!(
            serde_json::from_value::<ContentRef>(serde_json::json!(
                "APP-2026-0003"
            ))
            .unwrap(),
            gov
        );

        assert!(gov.is_governance());
        assert!(!content.is_governance());
        assert_eq!(gov.kind_str(), "governance");
        assert_eq!(content.kind_str(), "content");
        assert_eq!(content.as_content(), Some(ContentId::from(uuid)));
        assert!(content.as_governance().is_none());

        // Neither grammar: an error, not a panic and not a silent guess.
        assert!("not-an-id".parse::<ContentRef>().is_err());
        assert!(
            serde_json::from_value::<ContentRef>(serde_json::json!(
                "not-an-id"
            ))
            .is_err()
        );
    }

    /// Everything readable narrows into the reference `get_content` takes.
    #[test]
    fn every_readable_id_narrows_to_a_content_ref() {
        let uuid = Uuid::new_v4();
        for (label, got) in [
            ("PostId", ContentRef::from(PostId::from(uuid))),
            ("CommentId", ContentRef::from(CommentId::from(uuid))),
            ("ContentId", ContentRef::from(ContentId::from(uuid))),
        ] {
            assert_eq!(
                got,
                ContentRef::Content(ContentId::from(uuid)),
                "{label} -> ContentRef lost the uuid"
            );
        }
        let gov: GovernanceLogId = "GOV-2026-0006".parse().unwrap();
        assert_eq!(ContentRef::from(gov.clone()), ContentRef::Governance(gov));
    }

    /// Every id round-trips through its own `Display`, the new string-shaped
    /// ones included — same property the UUID newtypes carry.
    #[test]
    fn string_shaped_ids_round_trip_through_display() {
        let gov: GovernanceLogId = "GOV-2026-0006".parse().unwrap();
        assert_eq!(gov.to_string().parse::<GovernanceLogId>().unwrap(), gov);

        let r = ContentRef::Governance(gov);
        assert_eq!(r.to_string().parse::<ContentRef>().unwrap(), r);

        let r = ContentRef::Content(ContentId::new());
        assert_eq!(r.to_string().parse::<ContentRef>().unwrap(), r);
    }

    #[test]
    fn post_or_comment_post_variant() {
        let inner = PostId::new();
        let tagged = PostOrCommentId::Post(inner);
        assert!(tagged.is_post());
        assert!(!tagged.is_comment());
        assert_eq!(tagged.as_post(), Some(inner));
        assert_eq!(tagged.as_comment(), None);
        assert_eq!(tagged.as_uuid(), *inner.as_uuid());
        assert_eq!(tagged.kind_str(), "post");
    }

    #[test]
    fn post_or_comment_comment_variant() {
        let inner = CommentId::new();
        let tagged = PostOrCommentId::Comment(inner);
        assert!(tagged.is_comment());
        assert!(!tagged.is_post());
        assert_eq!(tagged.as_comment(), Some(inner));
        assert_eq!(tagged.as_post(), None);
        assert_eq!(tagged.as_uuid(), *inner.as_uuid());
        assert_eq!(tagged.kind_str(), "comment");
    }

    #[test]
    fn post_or_comment_from_conversions() {
        let post = PostId::new();
        let comment = CommentId::new();
        let via_post: PostOrCommentId = post.into();
        let via_comment: PostOrCommentId = comment.into();
        assert_eq!(via_post, PostOrCommentId::Post(post));
        assert_eq!(via_comment, PostOrCommentId::Comment(comment));
    }

    #[test]
    fn post_or_comment_display_is_kind_colon_uuid() {
        let post = PostId::new();
        let tagged = PostOrCommentId::Post(post);
        let rendered = tagged.to_string();
        assert!(rendered.starts_with("post:"));
        assert!(rendered.contains(&post.to_string()));
    }
}