falsegreen_agent/

genui.rs

//! Trusted, versioned presentation surfaces for the Agent terminal.
//!
//! This module deliberately contains no terminal control sequences and no
//! executable callbacks. A model may propose this typed tree, but the host
//! validates it, binds actions to host-owned operations, and invokes existing
//! Agent/Core/MCP paths only after rechecking the rendered identity.

use std::collections::{BTreeMap, BTreeSet};
use std::io::{self, Write};
use std::sync::{
    Arc,
    atomic::{AtomicU64, Ordering},
};

use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use sha2::{Digest, Sha256};
use thiserror::Error;
use unicode_width::UnicodeWidthChar;
use uuid::Uuid;

use crate::event::{EventError, EventKind, EventStore};
use crate::workspace::WorkspaceState;

/// FalseGreen-native read-only state projections, re-exported under the
/// existing GenUI namespace for integrations that own a surface host.
pub mod native {
    pub use crate::genui_native::*;
}

pub const PROTOCOL_ID: &str = "falsegreen.agent.genui.surface";
pub const SCHEMA_ID: &str = "surface-v1";
pub const PROTOCOL_MAJOR: u16 = 1;
pub const PROTOCOL_MINOR: u16 = 0;
pub const DEFAULT_MAX_DEPTH: usize = 32;
pub const DEFAULT_MAX_COMPONENTS: usize = 512;
pub const DEFAULT_MAX_ACTIONS: usize = 256;
pub const DEFAULT_MAX_TEXT_BYTES: usize = 64 * 1024;
pub const DEFAULT_MAX_ROWS: usize = 1_024;
pub const DEFAULT_MAX_COLUMNS: usize = 128;

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ProtocolVersion {
    pub major: u16,
    pub minor: u16,
}

impl ProtocolVersion {
    #[must_use]
    pub const fn current() -> Self {
        Self {
            major: PROTOCOL_MAJOR,
            minor: PROTOCOL_MINOR,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum UnsupportedComponentPolicy {
    Reject,
    Placeholder,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct HostCapabilities {
    pub protocol: ProtocolVersion,
    pub forward_compatible_minor: bool,
    pub supported_components: BTreeSet<String>,
    pub supported_actions: BTreeSet<ActionKind>,
    pub unsupported_component_policy: UnsupportedComponentPolicy,
    pub max_depth: usize,
    pub max_components: usize,
    pub max_actions: usize,
    pub terminal_width: usize,
}

impl Default for HostCapabilities {
    fn default() -> Self {
        Self {
            protocol: ProtocolVersion::current(),
            forward_compatible_minor: false,
            supported_components: ComponentKind::all_names()
                .into_iter()
                .map(str::to_owned)
                .collect(),
            supported_actions: [
                ActionKind::LocalPresentation,
                ActionKind::FormValueUpdate,
                ActionKind::Navigation,
                ActionKind::McpTool,
                ActionKind::Consequential,
            ]
            .into_iter()
            .collect(),
            unsupported_component_policy: UnsupportedComponentPolicy::Placeholder,
            max_depth: DEFAULT_MAX_DEPTH,
            max_components: DEFAULT_MAX_COMPONENTS,
            max_actions: DEFAULT_MAX_ACTIONS,
            terminal_width: 100,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct NegotiatedCapabilities {
    pub protocol: ProtocolVersion,
    pub unsupported_component_policy: UnsupportedComponentPolicy,
    pub supported_components: BTreeSet<String>,
    pub supported_actions: BTreeSet<ActionKind>,
    pub terminal_width: usize,
}

pub fn negotiate(
    offered: &[ProtocolVersion],
    host: &HostCapabilities,
) -> Result<NegotiatedCapabilities, GenUiError> {
    let version = offered
        .iter()
        .copied()
        .filter(|version| version.major == host.protocol.major)
        .filter(|version| {
            version.minor <= host.protocol.minor
                || host.forward_compatible_minor && version.minor >= host.protocol.minor
        })
        .max()
        .ok_or(GenUiError::UnsupportedProtocol {
            offered: offered.to_vec(),
            supported: host.protocol,
        })?;
    Ok(NegotiatedCapabilities {
        protocol: version,
        unsupported_component_policy: host.unsupported_component_policy,
        supported_components: host.supported_components.clone(),
        supported_actions: host.supported_actions.clone(),
        terminal_width: host.terminal_width.max(1),
    })
}

#[derive(Debug, Error, Clone, PartialEq, Eq)]
pub enum GenUiError {
    #[error("unsupported surface protocol; offered {offered:?}, host supports {supported:?}")]
    UnsupportedProtocol {
        offered: Vec<ProtocolVersion>,
        supported: ProtocolVersion,
    },
    #[error("surface protocol identity is invalid: {0}")]
    InvalidProtocol(String),
    #[error("surface validation failed: {0}")]
    InvalidSurface(String),
    #[error("unsupported component {component:?}")]
    UnsupportedComponent { component: String },
    #[error("unsupported action kind {0:?}")]
    UnsupportedAction(ActionKind),
    #[error("action binding is stale: {0}")]
    StaleAction(String),
    #[error("action binding does not match the rendered label or payload")]
    BindingMismatch,
    #[error("consequential action {0:?} was already activated")]
    DuplicateAction(String),
    #[error("MCP schema is unsupported: {0}")]
    UnsupportedMcpSchema(String),
    #[error("MCP submission is invalid: {0}")]
    InvalidMcpSubmission(String),
    #[error("action is not authorized by the host catalog: {0}")]
    UnauthorizedAction(String),
    #[error("host confirmation is required for this action")]
    ConfirmationRequired,
    #[error("GenUI session event could not be persisted: {0}")]
    EventStore(String),
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Surface {
    pub id: String,
    pub protocol: ProtocolVersion,
    pub schema: String,
    pub root: Component,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub actions: Vec<Action>,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
}

impl Surface {
    #[must_use]
    pub fn new(id: impl Into<String>, root: Component) -> Self {
        Self {
            id: id.into(),
            protocol: ProtocolVersion::current(),
            schema: SCHEMA_ID.to_owned(),
            root,
            actions: Vec::new(),
            metadata: BTreeMap::new(),
        }
    }

    pub fn validate(&self) -> Result<(), GenUiError> {
        self.validate_with_catalog(&HostCapabilities::default(), &ActionCatalog::default())
    }

    pub fn validate_with(&self, host: &HostCapabilities) -> Result<(), GenUiError> {
        self.validate_with_catalog(host, &ActionCatalog::default())
    }

    /// Validate only the structural/protocol portion of a Surface. This is
    /// used by the G5 composition adapter before host-issued action handles
    /// are checked against the real `ActionCatalog`; it never grants action
    /// admission on its own.
    pub fn validate_structure(&self, host: &HostCapabilities) -> Result<(), GenUiError> {
        self.validate_shape(host)
    }

    /// Validate a model-proposed surface against the exact host-owned action
    /// catalog. Shape validation alone is intentionally insufficient for
    /// executable actions.
    pub fn validate_with_catalog(
        &self,
        host: &HostCapabilities,
        catalog: &ActionCatalog,
    ) -> Result<(), GenUiError> {
        self.validate_shape(host)?;
        let surface_digest = self.binding_surface_digest()?;
        for action in &self.actions {
            catalog.validate_action(self, action, &surface_digest)?;
        }
        Ok(())
    }

    /// Alias used by integrations that make the authority boundary explicit.
    pub fn validate_for_host(
        &self,
        host: &HostCapabilities,
        catalog: &ActionCatalog,
    ) -> Result<(), GenUiError> {
        self.validate_with_catalog(host, catalog)
    }

    fn validate_shape(&self, host: &HostCapabilities) -> Result<(), GenUiError> {
        validate_id("surface", &self.id)?;
        if self.schema != SCHEMA_ID {
            return Err(GenUiError::InvalidProtocol(format!(
                "unknown schema identity {:?}",
                self.schema
            )));
        }
        if self.protocol.major != host.protocol.major
            || (self.protocol.minor > host.protocol.minor && !host.forward_compatible_minor)
        {
            return Err(GenUiError::UnsupportedProtocol {
                offered: vec![self.protocol],
                supported: host.protocol,
            });
        }
        // Component and action IDs share one surface-local namespace, and the
        // surface ID is also reserved within that surface. This prevents raw
        // IDs from becoming ambiguous at a host boundary.
        let mut component_ids = BTreeSet::new();
        let mut count = 0usize;
        validate_component(
            &self.root,
            1,
            &mut count,
            host.max_depth,
            host.max_components,
            &mut component_ids,
            host,
        )?;
        if component_ids.contains(&self.id) {
            return Err(GenUiError::InvalidSurface(format!(
                "surface/component ID collision {:?}",
                self.id
            )));
        }
        if self.actions.len() > host.max_actions {
            return Err(GenUiError::InvalidSurface(format!(
                "action count {} exceeds bound {}",
                self.actions.len(),
                host.max_actions
            )));
        }
        let mut action_ids = BTreeSet::new();
        for action in &self.actions {
            if !action_ids.insert(action.id.clone()) {
                return Err(GenUiError::InvalidSurface(format!(
                    "duplicate action ID {:?}",
                    action.id
                )));
            }
            if component_ids.contains(&action.id) {
                return Err(GenUiError::InvalidSurface(format!(
                    "component/action ID collision {:?}",
                    action.id
                )));
            }
            if self.id == action.id {
                return Err(GenUiError::InvalidSurface(format!(
                    "surface/action ID collision {:?}",
                    action.id
                )));
            }
            action.validate(&self.id, host)?;
        }
        Ok(())
    }

    pub fn canonical_json(&self) -> Result<Vec<u8>, GenUiError> {
        // Digesting a surface is an identity operation and does not itself
        // grant execution authority. Host admission is performed by
        // `validate_with_catalog` before activation.
        self.validate_shape(&HostCapabilities::default())?;
        canonical_json_bytes(self).map_err(|error| GenUiError::InvalidSurface(error.to_string()))
    }

    pub fn digest(&self) -> Result<String, GenUiError> {
        // The executable binding digest intentionally covers the structural
        // surface only. Each action's ID, label, kind, and state identity are
        // validated independently so one mutated sibling can be suppressed
        // without revoking every other valid action on the surface.
        self.binding_surface_digest()
    }

    /// Identity of the structural surface that owns an executable action.
    /// Action entries are validated independently so a single mutated action
    /// can be revoked without hiding unchanged executable siblings.
    fn binding_surface_digest(&self) -> Result<String, GenUiError> {
        let mut structural = self.clone();
        structural.actions.clear();
        structural.canonical_json().map(|bytes| sha256_hex(&bytes))
    }
}

#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct Component {
    pub id: String,
    #[serde(flatten)]
    pub kind: ComponentKind,
}

impl<'de> Deserialize<'de> for Component {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let mut object = Map::<String, Value>::deserialize(deserializer)?;
        let id = object
            .remove("id")
            .ok_or_else(|| serde::de::Error::missing_field("id"))?;
        let id = String::deserialize(id).map_err(serde::de::Error::custom)?;
        let kind =
            ComponentKind::deserialize(Value::Object(object)).map_err(serde::de::Error::custom)?;
        Ok(Self { id, kind })
    }
}

impl Component {
    #[must_use]
    pub fn text(id: impl Into<String>, text: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            kind: ComponentKind::Text { text: text.into() },
        }
    }

    #[must_use]
    pub fn status(
        id: impl Into<String>,
        label: impl Into<String>,
        value: impl Into<String>,
    ) -> Self {
        Self {
            id: id.into(),
            kind: ComponentKind::Status {
                label: label.into(),
                value: value.into(),
                level: StatusLevel::Info,
            },
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
pub enum ComponentKind {
    Text {
        text: String,
    },
    Markdown {
        markdown: String,
    },
    Status {
        label: String,
        value: String,
        level: StatusLevel,
    },
    Progress {
        label: String,
        current: u64,
        total: Option<u64>,
    },
    Table {
        columns: Vec<String>,
        rows: Vec<Vec<String>>,
    },
    KeyValue {
        entries: BTreeMap<String, String>,
    },
    Diff {
        before: String,
        after: String,
    },
    TestResults {
        passed: u64,
        failed: u64,
        skipped: u64,
        details: Vec<String>,
    },
    Form {
        fields: Vec<FormField>,
    },
    Choice {
        label: String,
        options: Vec<ChoiceOption>,
        selected: Option<String>,
    },
    Evidence {
        title: String,
        items: Vec<EvidenceItem>,
    },
    Timeline {
        entries: Vec<TimelineEntry>,
    },
    Stack {
        children: Vec<Component>,
    },
    Columns {
        columns: Vec<Vec<Component>>,
    },
}

impl ComponentKind {
    #[must_use]
    pub fn name(&self) -> &'static str {
        match self {
            Self::Text { .. } => "text",
            Self::Markdown { .. } => "markdown",
            Self::Status { .. } => "status",
            Self::Progress { .. } => "progress",
            Self::Table { .. } => "table",
            Self::KeyValue { .. } => "key_value",
            Self::Diff { .. } => "diff",
            Self::TestResults { .. } => "test_results",
            Self::Form { .. } => "form",
            Self::Choice { .. } => "choice",
            Self::Evidence { .. } => "evidence",
            Self::Timeline { .. } => "timeline",
            Self::Stack { .. } => "stack",
            Self::Columns { .. } => "columns",
        }
    }

    #[must_use]
    pub fn all_names() -> Vec<&'static str> {
        vec![
            "text",
            "markdown",
            "status",
            "progress",
            "table",
            "key_value",
            "diff",
            "test_results",
            "form",
            "choice",
            "evidence",
            "timeline",
            "stack",
            "columns",
        ]
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StatusLevel {
    Info,
    Success,
    Warning,
    Error,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FormField {
    pub id: String,
    pub label: String,
    pub field_type: FieldType,
    pub required: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub value: Option<Value>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub choices: Vec<String>,
    /// Exact JSON values represented by `choices`.  The legacy display labels
    /// remain strings for renderer compatibility; this parallel vector keeps
    /// booleans and integers from being coerced through presentation text.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub choice_values: Vec<Value>,
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub constraints: BTreeMap<String, Value>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FieldType {
    String,
    Number,
    Integer,
    Boolean,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ChoiceOption {
    pub value: String,
    pub label: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct EvidenceItem {
    pub label: String,
    pub value: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TimelineEntry {
    pub label: String,
    pub detail: String,
    pub state: TimelineState,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TimelineState {
    Pending,
    Active,
    Complete,
    Failed,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ActionKind {
    LocalPresentation,
    FormValueUpdate,
    Navigation,
    McpTool,
    Consequential,
}

/// Explicit executable transport identity retained by every host-owned
/// catalog binding. `Auto` is valid only while resolving an untrusted
/// discovery value; it must never survive into an executable binding.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ActionSourceType {
    Auto,
    Mcp,
    HostLocal,
}

/// Canonical executable compatibility table shared by every trust boundary.
/// `Auto` is discovery-only and is intentionally absent from this table.
/// Keeping this as the one predicate prevents a legacy binder, renderer, or
/// durable replay path from inferring transport from an action kind.
#[must_use]
pub const fn action_kind_source_compatible(
    action_kind: ActionKind,
    source_type: ActionSourceType,
) -> bool {
    matches!(
        (action_kind, source_type),
        (ActionKind::McpTool, ActionSourceType::Mcp)
            | (ActionKind::Consequential, ActionSourceType::Mcp)
            | (ActionKind::Consequential, ActionSourceType::HostLocal)
            | (ActionKind::Navigation, ActionSourceType::HostLocal)
            | (ActionKind::FormValueUpdate, ActionSourceType::HostLocal)
            | (ActionKind::LocalPresentation, ActionSourceType::HostLocal)
    )
}

/// Model-visible action presentation. Executable authority is deliberately not
/// serialized here; the opaque ID is resolved against the host catalog.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Action {
    pub id: String,
    pub label: String,
    pub kind: ActionKind,
    pub state_digest: String,
}

/// Host-only binding. This type intentionally has no serde implementation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedActionBinding {
    action_id: String,
    action_kind: ActionKind,
    source_type: ActionSourceType,
    label_digest: String,
    surface_id: String,
    surface_digest: String,
    state_digest: String,
    state_generation: u64,
    principal: String,
    authorization_context: String,
    session_id: String,
    provider_id: String,
    server_id: String,
    tool_name: String,
    remote_tool_name: String,
    schema_digest: String,
    policy_version: u64,
    policy_digest: String,
    requires_confirmation: bool,
}

impl ResolvedActionBinding {
    #[must_use]
    pub fn action_id(&self) -> &str {
        &self.action_id
    }
    #[must_use]
    pub fn action_kind(&self) -> ActionKind {
        self.action_kind
    }
    #[must_use]
    pub fn source_type(&self) -> ActionSourceType {
        self.source_type
    }
    #[must_use]
    pub fn label_digest(&self) -> &str {
        &self.label_digest
    }
    #[must_use]
    pub fn surface_id(&self) -> &str {
        &self.surface_id
    }
    #[must_use]
    pub fn surface_digest(&self) -> &str {
        &self.surface_digest
    }
    #[must_use]
    pub fn state_digest(&self) -> &str {
        &self.state_digest
    }
    #[must_use]
    pub fn state_generation(&self) -> u64 {
        self.state_generation
    }
    #[must_use]
    pub fn principal(&self) -> &str {
        &self.principal
    }
    #[must_use]
    pub fn authorization_context(&self) -> &str {
        &self.authorization_context
    }
    #[must_use]
    pub fn session_id(&self) -> &str {
        &self.session_id
    }
    #[must_use]
    pub fn provider_id(&self) -> &str {
        &self.provider_id
    }
    #[must_use]
    pub fn server_id(&self) -> &str {
        &self.server_id
    }
    #[must_use]
    pub fn tool_name(&self) -> &str {
        &self.tool_name
    }
    #[must_use]
    pub fn remote_tool_name(&self) -> &str {
        &self.remote_tool_name
    }
    #[must_use]
    pub fn schema_digest(&self) -> &str {
        &self.schema_digest
    }
    #[must_use]
    pub fn policy_version(&self) -> u64 {
        self.policy_version
    }
    #[must_use]
    pub fn policy_digest(&self) -> &str {
        &self.policy_digest
    }
    #[must_use]
    pub fn requires_confirmation(&self) -> bool {
        self.requires_confirmation
    }
}

#[derive(Debug, Clone)]
pub struct HostConfirmation {
    identity: Value,
    payload: Value,
}

impl HostConfirmation {
    pub(crate) fn identity(&self) -> &Value {
        &self.identity
    }

    pub(crate) fn payload(&self) -> &Value {
        &self.payload
    }
}

/// Host-owned action bindings. A model-proposed action is never executable
/// unless an exact opaque ID is present in this catalog.
#[derive(Debug, Clone)]
pub struct ActionCatalog {
    bindings: BTreeMap<String, ResolvedActionBinding>,
    current_states: BTreeMap<(String, String), HostStateIdentity>,
    // Keys are populated only after the host has established or restored the
    // corresponding row in EventStore.  Renderer admission uses this marker
    // in addition to the in-memory identity so an unseeded catalog can never
    // expose an executable action.
    durable_state_keys: BTreeSet<(String, String)>,
    action_owners: BTreeMap<String, String>,
    /// Mutation-time authority token owned by this catalog. It is deliberately
    /// process-local metadata rather than serialized model input.
    generation: Arc<AtomicU64>,
    /// For a staged clone, the live generation from which this catalog was
    /// copied. Live catalogs keep this equal to `generation`.
    base_generation: u64,
    mutation_depth: u8,
    mutation_changed: bool,
}

impl Default for ActionCatalog {
    fn default() -> Self {
        Self {
            bindings: BTreeMap::new(),
            current_states: BTreeMap::new(),
            durable_state_keys: BTreeSet::new(),
            action_owners: BTreeMap::new(),
            generation: Arc::new(AtomicU64::new(1)),
            base_generation: 1,
            mutation_depth: 0,
            mutation_changed: false,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct HostStateIdentity {
    generation: u64,
    digest: String,
    authorization_context: String,
}

impl ActionCatalog {
    #[must_use]
    pub fn generation(&self) -> u64 {
        self.generation.load(Ordering::Acquire)
    }

    #[must_use]
    pub(crate) fn base_generation(&self) -> u64 {
        self.base_generation
    }

    /// Clone the live catalog into an isolated staging catalog. Mutations on
    /// the clone advance only its local token; publication performs the one
    /// live-generation increment after the final CAS succeeds.
    #[must_use]
    pub(crate) fn clone_for_staging(&self) -> Self {
        let mut staged = self.clone();
        let generation = self.generation();
        staged.generation = Arc::new(AtomicU64::new(generation));
        staged.base_generation = generation;
        staged.mutation_depth = 0;
        staged.mutation_changed = false;
        staged
    }

    pub(crate) fn publish_staged(&mut self, staged: Self) {
        let next_generation = self.generation().saturating_add(1);
        // Preserve the live catalog's shared generation Arc. Ordinary clones
        // intentionally share this token so they observe the publication and
        // still detect an ABA mutation; only staging clones receive isolated
        // tokens in `clone_for_staging`.
        self.bindings = staged.bindings;
        self.current_states = staged.current_states;
        self.durable_state_keys = staged.durable_state_keys;
        self.action_owners = staged.action_owners;
        self.base_generation = next_generation;
        self.mutation_depth = 0;
        self.mutation_changed = false;
        self.generation.store(next_generation, Ordering::Release);
    }

    fn bump_generation(&mut self) {
        if self.mutation_depth > 0 {
            self.mutation_changed = true;
            return;
        }
        let _ = self
            .generation
            .fetch_update(Ordering::AcqRel, Ordering::Acquire, |value| {
                Some(value.saturating_add(1))
            });
    }

    fn with_mutation<R>(
        &mut self,
        operation: impl FnOnce(&mut Self) -> Result<R, GenUiError>,
    ) -> Result<R, GenUiError> {
        // Run the complete operation against an isolated snapshot.  A
        // multi-step mutation (for example bind + state + remote identity)
        // therefore has no observable effect until every step succeeds.
        let original_generation = self.generation();
        let live_catalog = original_generation == self.base_generation;
        let original_bindings = self.bindings.clone();
        let original_states = self.current_states.clone();
        let original_durable_keys = self.durable_state_keys.clone();
        let original_owners = self.action_owners.clone();
        let mut staged = self.clone_for_staging();
        staged.mutation_depth = 0;
        staged.mutation_changed = false;
        let result = operation(&mut staged);
        let Ok(value) = result else {
            // The live catalog and its shared generation token are untouched.
            return result;
        };
        let changed = staged.bindings != original_bindings
            || staged.current_states != original_states
            || staged.durable_state_keys != original_durable_keys
            || staged.action_owners != original_owners;
        if changed {
            self.bindings = staged.bindings;
            self.current_states = staged.current_states;
            self.durable_state_keys = staged.durable_state_keys;
            self.action_owners = staged.action_owners;
            if live_catalog {
                self.base_generation = original_generation.saturating_add(1);
            }
            let _ = self
                .generation
                .fetch_update(Ordering::AcqRel, Ordering::Acquire, |value| {
                    // The live token is still expected to be the snapshot
                    // generation because publication is serialized by the
                    // host guard.  Preserve monotonicity if a caller shares
                    // a catalog clone and advances it independently.
                    Some(value.max(original_generation).saturating_add(1))
                });
        }
        self.mutation_depth = 0;
        self.mutation_changed = false;
        Ok(value)
    }

    pub fn validate_source_type(
        action_kind: ActionKind,
        source_type: ActionSourceType,
    ) -> Result<(), GenUiError> {
        if action_kind_source_compatible(action_kind, source_type) {
            Ok(())
        } else {
            Err(GenUiError::UnauthorizedAction(format!(
                "invalid action kind/source type pair: {action_kind:?}/{source_type:?}"
            )))
        }
    }

    #[must_use]
    pub fn new_action_id() -> String {
        format!("gui_action_{}", Uuid::new_v4().simple())
    }

    /// Bind an MCP action when the exposed namespace and the exact remote
    /// tool identity are both available from trusted discovery. The durable
    /// current state must already exist and match the action; this method can
    /// never seed or advance that state.
    #[allow(clippy::too_many_arguments)]
    pub fn bind_mcp_action_with_remote(
        &mut self,
        store: &EventStore,
        action: &Action,
        surface_id: &str,
        surface_digest: &str,
        session_id: &str,
        principal: &str,
        provider_id: &str,
        server_id: &str,
        exposed_tool_name: &str,
        remote_tool_name: &str,
        schema_digest: &str,
        requires_confirmation: bool,
    ) -> Result<(), GenUiError> {
        // Reject an invalid source/kind pair before reading or mutating any
        // durable or in-memory authority. This is the public MCP boundary;
        // local presentation actions must use the explicit host-local API.
        Self::validate_source_type(action.kind, ActionSourceType::Mcp)?;
        let Some((state_generation, state_digest, authorization_context)) = store
            .genui_current_state(session_id, principal)
            .map_err(event_error)?
        else {
            return Err(GenUiError::StaleAction(
                "a durable trusted current state must exist before binding".to_owned(),
            ));
        };
        if state_digest != action.state_digest {
            return Err(GenUiError::StaleAction(
                "action state digest does not match durable trusted state".to_owned(),
            ));
        }
        validate_id("remote tool", remote_tool_name)?;
        let policy_digest = sha256_hex(
            format!(
                "falsegreen.tool-policy.v1|{}|1",
                if requires_confirmation {
                    "consequential"
                } else {
                    "read_only"
                }
            )
            .as_bytes(),
        );
        self.with_mutation(|catalog| {
            catalog.bind_action_with_source(
                action,
                surface_id,
                surface_digest,
                session_id,
                principal,
                &authorization_context,
                state_generation,
                &state_digest,
                provider_id,
                server_id,
                exposed_tool_name,
                schema_digest,
                1,
                &policy_digest,
                requires_confirmation,
                ActionSourceType::Mcp,
            )?;
            catalog.set_current_state(
                session_id,
                principal,
                state_generation,
                &state_digest,
                &authorization_context,
            )?;
            catalog.set_remote_tool_name(action.id.as_str(), remote_tool_name)
        })
    }

    #[allow(clippy::too_many_arguments)]
    pub(crate) fn bind_mcp_action_with_context(
        &mut self,
        action: &Action,
        surface_id: &str,
        surface_digest: &str,
        session_id: &str,
        principal: &str,
        authorization_context: &str,
        state_generation: u64,
        state_digest: &str,
        provider_id: &str,
        server_id: &str,
        tool_name: &str,
        schema_digest: &str,
        policy_version: u64,
        policy_digest: &str,
        requires_confirmation: bool,
        source_type: ActionSourceType,
    ) -> Result<(), GenUiError> {
        // Compatibility is explicit at the call site.  This legacy name is
        // retained only for source compatibility with in-crate G1-G4 code;
        // it no longer infers HostLocal/MCP from ActionKind.
        self.bind_action_with_source(
            action,
            surface_id,
            surface_digest,
            session_id,
            principal,
            authorization_context,
            state_generation,
            state_digest,
            provider_id,
            server_id,
            tool_name,
            schema_digest,
            policy_version,
            policy_digest,
            requires_confirmation,
            source_type,
        )
    }

    /// Public host-local binding boundary. The explicit source type is stored
    /// in the resulting executable binding and is never inferred from the
    /// provider/server strings.
    #[allow(clippy::too_many_arguments)]
    pub fn bind_host_local_action_with_context(
        &mut self,
        action: &Action,
        surface_id: &str,
        surface_digest: &str,
        session_id: &str,
        principal: &str,
        authorization_context: &str,
        state_generation: u64,
        state_digest: &str,
        provider_id: &str,
        server_id: &str,
        tool_name: &str,
        schema_digest: &str,
        policy_version: u64,
        policy_digest: &str,
        requires_confirmation: bool,
    ) -> Result<(), GenUiError> {
        self.bind_action_with_source(
            action,
            surface_id,
            surface_digest,
            session_id,
            principal,
            authorization_context,
            state_generation,
            state_digest,
            provider_id,
            server_id,
            tool_name,
            schema_digest,
            policy_version,
            policy_digest,
            requires_confirmation,
            ActionSourceType::HostLocal,
        )
    }

    /// Bind a host-local action with an explicit source identity. The source
    /// type is stored in the executable binding so legacy execution paths
    /// cannot infer MCP merely from a provider/server name.
    #[allow(clippy::too_many_arguments)]
    pub(crate) fn bind_action_with_source(
        &mut self,
        action: &Action,
        surface_id: &str,
        surface_digest: &str,
        session_id: &str,
        principal: &str,
        authorization_context: &str,
        state_generation: u64,
        state_digest: &str,
        provider_id: &str,
        server_id: &str,
        tool_name: &str,
        schema_digest: &str,
        policy_version: u64,
        policy_digest: &str,
        requires_confirmation: bool,
        source_type: ActionSourceType,
    ) -> Result<(), GenUiError> {
        Self::validate_source_type(action.kind, source_type)?;
        action.validate(surface_id, &HostCapabilities::default())?;
        let label_digest = sha256_hex(normalize_action_label(&action.label)?.as_bytes());
        validate_digest("surface", surface_digest)?;
        validate_digest("schema", schema_digest)?;
        validate_digest("policy", policy_digest)?;
        if state_digest != action.state_digest {
            return Err(GenUiError::StaleAction(
                "host state digest does not match the presented action".to_owned(),
            ));
        }
        for (name, value) in [
            ("session", session_id),
            ("principal", principal),
            ("authorization context", authorization_context),
            ("provider", provider_id),
            ("server", server_id),
            ("tool", tool_name),
        ] {
            validate_id(name, value)?;
        }
        if requires_confirmation != (action.kind == ActionKind::Consequential) {
            return Err(GenUiError::UnauthorizedAction(
                "host policy and action kind disagree".to_owned(),
            ));
        }
        let state_key = (session_id.to_owned(), principal.to_owned());
        if let Some(current) = self.current_states.get(&state_key) {
            if state_generation > current.generation {
                return Err(GenUiError::StaleAction(
                    "binding cannot advance trusted state generation".to_owned(),
                ));
            }
            if state_generation == current.generation
                && (state_digest != current.digest
                    || authorization_context != current.authorization_context)
            {
                return Err(GenUiError::StaleAction(
                    "binding state identity does not match the current trusted state".to_owned(),
                ));
            }
        }
        self.bindings.insert(
            action.id.clone(),
            ResolvedActionBinding {
                action_id: action.id.clone(),
                action_kind: action.kind,
                source_type,
                label_digest,
                surface_id: surface_id.to_owned(),
                surface_digest: surface_digest.to_owned(),
                state_digest: state_digest.to_owned(),
                state_generation,
                principal: principal.to_owned(),
                authorization_context: authorization_context.to_owned(),
                session_id: session_id.to_owned(),
                provider_id: provider_id.to_owned(),
                server_id: server_id.to_owned(),
                tool_name: tool_name.to_owned(),
                remote_tool_name: tool_name.to_owned(),
                schema_digest: schema_digest.to_owned(),
                policy_version,
                policy_digest: policy_digest.to_owned(),
                requires_confirmation,
            },
        );
        self.action_owners
            .entry(action.id.clone())
            .or_insert_with(|| "__surface_root__".to_owned());
        self.bump_generation();
        Ok(())
    }

    /// Update the trusted state/authorization snapshot used for activation.
    /// Generations are host-owned and cannot move backwards or change their
    /// digest in place. Model-proposed Surface state is never sufficient by
    /// itself.
    pub(crate) fn set_current_state(
        &mut self,
        session_id: &str,
        principal: &str,
        generation: u64,
        digest: &str,
        authorization_context: &str,
    ) -> Result<(), GenUiError> {
        validate_id("session", session_id)?;
        validate_id("principal", principal)?;
        validate_id("authorization context", authorization_context)?;
        if digest.is_empty() {
            return Err(GenUiError::StaleAction(
                "trusted state digest must not be empty".to_owned(),
            ));
        }
        let key = (session_id.to_owned(), principal.to_owned());
        if let Some(previous) = self.current_states.get(&key) {
            if generation < previous.generation {
                return Err(GenUiError::StaleAction(
                    "trusted state generation cannot rewind".to_owned(),
                ));
            }
            if generation == previous.generation
                && (digest != previous.digest
                    || authorization_context != previous.authorization_context)
            {
                return Err(GenUiError::StaleAction(
                    "trusted state identity cannot change without advancing generation".to_owned(),
                ));
            }
        }
        let next = HostStateIdentity {
            generation,
            digest: digest.to_owned(),
            authorization_context: authorization_context.to_owned(),
        };
        let changed =
            self.current_states.get(&key) != Some(&next) || !self.durable_state_keys.contains(&key);
        self.current_states.insert(key.clone(), next);
        // `set_current_state` is crate-private and exists for trusted host
        // transitions plus focused in-crate tests. Public callers can only
        // reach this through the durable transition/restore APIs below.
        self.durable_state_keys.insert(key);
        if changed {
            self.bump_generation();
        }
        Ok(())
    }

    /// Rehydrate a trusted current-state snapshot after process restart. A
    /// durable state that is older than an already-advanced in-memory state
    /// is rejected rather than rewinding the catalog.
    pub fn restore_current_state(
        &mut self,
        store: &EventStore,
        session_id: &str,
        principal: &str,
    ) -> Result<bool, GenUiError> {
        let Some((generation, digest, authorization_context)) = store
            .genui_current_state(session_id, principal)
            .map_err(event_error)?
        else {
            return Ok(false);
        };
        self.set_current_state(
            session_id,
            principal,
            generation,
            &digest,
            &authorization_context,
        )?;
        self.durable_state_keys
            .insert((session_id.to_owned(), principal.to_owned()));
        Ok(true)
    }

    /// Associate an executable action with the component subtree that owns
    /// it. The renderer uses this host-owned association to revoke only
    /// actions under an unsupported component.
    pub fn bind_action_owner(
        &mut self,
        action_id: &str,
        component_id: &str,
    ) -> Result<(), GenUiError> {
        if !self.bindings.contains_key(action_id) {
            return Err(GenUiError::UnauthorizedAction(
                "action ID is not present in host catalog".to_owned(),
            ));
        }
        validate_id("component", component_id)?;
        if let Some(existing) = self.action_owners.get(action_id)
            && existing != component_id
            && existing != "__surface_root__"
        {
            return Err(GenUiError::UnauthorizedAction(
                "action owner is already bound to a different component".to_owned(),
            ));
        }
        let changed = self.action_owners.get(action_id).map(String::as_str) != Some(component_id);
        self.action_owners
            .insert(action_id.to_owned(), component_id.to_owned());
        if changed {
            self.bump_generation();
        }
        Ok(())
    }

    pub(crate) fn set_remote_tool_name(
        &mut self,
        action_id: &str,
        remote_tool_name: &str,
    ) -> Result<(), GenUiError> {
        validate_id("remote tool", remote_tool_name)?;
        let binding = self
            .bindings
            .get_mut(action_id)
            .ok_or_else(|| GenUiError::UnauthorizedAction("unknown action ID".to_owned()))?;
        if binding.remote_tool_name != remote_tool_name {
            binding.remote_tool_name = remote_tool_name.to_owned();
            self.bump_generation();
        }
        Ok(())
    }

    pub fn validate_surface(
        &self,
        surface: &Surface,
        host: &HostCapabilities,
    ) -> Result<(), GenUiError> {
        surface.validate_shape(host)?;
        let digest = surface.binding_surface_digest()?;
        for action in &surface.actions {
            self.validate_action(surface, action, &digest)?;
        }
        Ok(())
    }

    /// Commit the negotiated renderer admission to the executable catalog.
    /// Any action on a degraded/unsupported surface is revoked before it can
    /// be focused or activated.
    pub(crate) fn admit_rendered_surface(
        &mut self,
        surface: &Surface,
        capabilities: &NegotiatedCapabilities,
    ) -> Result<(), GenUiError> {
        self.with_mutation(|catalog| catalog.admit_rendered_surface_inner(surface, capabilities))
    }

    fn admit_rendered_surface_inner(
        &mut self,
        surface: &Surface,
        capabilities: &NegotiatedCapabilities,
    ) -> Result<(), GenUiError> {
        let host = HostCapabilities {
            protocol: capabilities.protocol,
            supported_components: capabilities.supported_components.clone(),
            supported_actions: capabilities.supported_actions.clone(),
            unsupported_component_policy: capabilities.unsupported_component_policy,
            terminal_width: capabilities.terminal_width.max(1),
            ..HostCapabilities::default()
        };
        surface.validate_shape(&host)?;
        let surface_digest = surface.binding_surface_digest()?;
        let unsupported = unsupported_component_ids(&surface.root, &host.supported_components);
        for action in &surface.actions {
            let owned_by_unsupported =
                self.action_owners
                    .get(&action.id)
                    .map_or(!unsupported.is_empty(), |owner| {
                        if owner == "__surface_root__" {
                            unsupported.contains(&surface.root.id)
                        } else {
                            unsupported.iter().any(|root| {
                                root == owner || component_contains_id(&surface.root, root, owner)
                            })
                        }
                    });
            let has_valid_durable_state = self.bindings.get(&action.id).is_some_and(|binding| {
                self.durable_state_keys
                    .contains(&(binding.session_id.clone(), binding.principal.clone()))
                    && self.current_state_matches(binding)
            });
            if !capabilities.supported_actions.contains(&action.kind)
                || owned_by_unsupported
                || !has_valid_durable_state
                || self
                    .validate_action(surface, action, &surface_digest)
                    .is_err()
            {
                self.remove(&action.id);
            }
        }
        Ok(())
    }

    /// Durable-state-aware renderer admission. This is the canonical path for
    /// surfaces backed by an EventStore: a row is read and compared to the
    /// host binding before an action is retained in the executable catalog.
    pub fn admit_rendered_surface_with_store(
        &mut self,
        surface: &Surface,
        capabilities: &NegotiatedCapabilities,
        store: &EventStore,
    ) -> Result<(), GenUiError> {
        self.with_mutation(|catalog| {
            catalog.admit_rendered_surface_with_store_inner(surface, capabilities, store)
        })
    }

    fn admit_rendered_surface_with_store_inner(
        &mut self,
        surface: &Surface,
        capabilities: &NegotiatedCapabilities,
        store: &EventStore,
    ) -> Result<(), GenUiError> {
        // Rehydrate the durable rows first so this path works after process
        // restart even when the caller constructed a fresh catalog. Missing
        // or malformed rows are deliberately left unmarked and are revoked
        // by the admission pass below.
        for action in &surface.actions {
            let Some(binding) = self.bindings.get(&action.id).cloned() else {
                continue;
            };
            if let Some((generation, digest, authorization_context)) = store
                .genui_current_state(&binding.session_id, &binding.principal)
                .map_err(event_error)?
            {
                let _ = self.set_current_state(
                    &binding.session_id,
                    &binding.principal,
                    generation,
                    &digest,
                    &authorization_context,
                );
            }
        }
        self.admit_rendered_surface_inner(surface, capabilities)?;
        let surface_digest = surface.binding_surface_digest()?;
        let action_ids = surface
            .actions
            .iter()
            .map(|action| action.id.clone())
            .collect::<Vec<_>>();
        for action_id in action_ids {
            let valid = self.bindings.get(&action_id).is_some_and(|_| {
                surface
                    .actions
                    .iter()
                    .find(|action| action.id == action_id)
                    .is_some_and(|action| {
                        self.validate_action(surface, action, &surface_digest)
                            .is_ok()
                            && self
                                .validate_durable_current_action(store, &action_id)
                                .is_ok()
                    })
            });
            if !valid {
                self.remove(&action_id);
            } else if let Some(binding) = self.bindings.get(&action_id) {
                self.durable_state_keys
                    .insert((binding.session_id.clone(), binding.principal.clone()));
            }
        }
        Ok(())
    }

    pub fn validate_action(
        &self,
        surface: &Surface,
        action: &Action,
        surface_digest: &str,
    ) -> Result<(), GenUiError> {
        action.validate(&surface.id, &HostCapabilities::default())?;
        let binding = self.bindings.get(&action.id).ok_or_else(|| {
            GenUiError::UnauthorizedAction("action ID is not present in host catalog".to_owned())
        })?;
        Self::validate_source_type(binding.action_kind, binding.source_type)?;
        let label = normalize_action_label(&action.label)?;
        if binding.action_id != action.id
            || binding.action_kind != action.kind
            || binding.label_digest != sha256_hex(label.as_bytes())
            || binding.surface_id != surface.id
            || binding.surface_digest != surface_digest
            || binding.state_digest != action.state_digest
            || label.is_empty()
            || binding.requires_confirmation != (action.kind == ActionKind::Consequential)
            || !self
                .current_states
                .get(&(binding.session_id.clone(), binding.principal.clone()))
                .is_some_and(|state| {
                    state.generation == binding.state_generation
                        && state.digest == binding.state_digest
                        && state.authorization_context == binding.authorization_context
                })
        {
            return Err(GenUiError::StaleAction(
                "host binding no longer matches rendered action".to_owned(),
            ));
        }
        Ok(())
    }

    #[must_use]
    pub fn resolve(&self, action_id: &str) -> Option<&ResolvedActionBinding> {
        self.bindings.get(action_id)
    }

    pub fn remove(&mut self, action_id: &str) -> bool {
        let owner_removed = self.action_owners.remove(action_id).is_some();
        let binding_removed = self.bindings.remove(action_id).is_some();
        if owner_removed || binding_removed {
            self.bump_generation();
        }
        binding_removed
    }

    /// Clear all executable catalog authority in one mutation transaction.
    pub fn clear(&mut self) {
        if self.bindings.is_empty()
            && self.current_states.is_empty()
            && self.durable_state_keys.is_empty()
            && self.action_owners.is_empty()
        {
            return;
        }
        self.bindings.clear();
        self.current_states.clear();
        self.durable_state_keys.clear();
        self.action_owners.clear();
        self.bump_generation();
    }

    #[must_use]
    pub fn digest(&self) -> String {
        let entries: Vec<Value> = self
            .bindings
            .values()
            .map(|b| {
                serde_json::json!({
                    "action_id": b.action_id,
                    "action_kind": b.action_kind,
                    "source_type": b.source_type,
                    "label_digest": b.label_digest,
                    "surface_id": b.surface_id,
                    "surface_digest": b.surface_digest,
                    "state_digest": b.state_digest,
                    "state_generation": b.state_generation,
                    "principal": b.principal,
                    "authorization_context": b.authorization_context,
                    "session_id": b.session_id,
                    "provider_id": b.provider_id,
                    "server_id": b.server_id,
                    "tool_name": b.tool_name,
                    "remote_tool_name": b.remote_tool_name,
                    "schema_digest": b.schema_digest,
                    "policy_version": b.policy_version,
                    "policy_digest": b.policy_digest,
                    "requires_confirmation": b.requires_confirmation,
                    "owner_component_id": self.action_owners.get(&b.action_id),
                })
            })
            .collect();
        digest_json(&entries)
    }

    pub fn present_action(
        &self,
        store: &mut EventStore,
        session_id: &str,
        action_id: &str,
    ) -> Result<(), GenUiError> {
        let binding = self
            .bindings
            .get(action_id)
            .ok_or_else(|| GenUiError::UnauthorizedAction("unknown action ID".to_owned()))?;
        if binding.session_id != session_id {
            return Err(GenUiError::UnauthorizedAction(
                "session is not bound to this action".to_owned(),
            ));
        }
        if !self.current_state_matches(binding) {
            return Err(GenUiError::StaleAction("trusted state changed".to_owned()));
        }
        self.validate_durable_current_action(store, action_id)?;
        store
            .append_genui_lifecycle(
                session_id,
                EventKind::GenUiActionPresented,
                &identity_payload(binding, None),
            )
            .map(|_| ())
            .map_err(event_error)
    }

    pub fn request_confirmation(
        &self,
        store: &mut EventStore,
        session_id: &str,
        action_id: &str,
        payload: &Value,
    ) -> Result<HostConfirmation, GenUiError> {
        let binding = self
            .bindings
            .get(action_id)
            .ok_or_else(|| GenUiError::UnauthorizedAction("unknown action ID".to_owned()))?;
        if !binding.requires_confirmation {
            return Err(GenUiError::UnauthorizedAction(
                "read-only action does not require confirmation".to_owned(),
            ));
        }
        if binding.session_id != session_id {
            return Err(GenUiError::UnauthorizedAction(
                "session is not bound to this action".to_owned(),
            ));
        }
        if !self.current_state_matches(binding) {
            return Err(GenUiError::StaleAction("trusted state changed".to_owned()));
        }
        self.validate_durable_current_action(store, action_id)?;
        let identity = identity_payload(binding, Some(payload));
        store
            .append_genui_lifecycle(
                session_id,
                EventKind::GenUiActionConfirmationRequested,
                &identity,
            )
            .map_err(event_error)?;
        Ok(HostConfirmation {
            identity,
            payload: payload.clone(),
        })
    }

    pub(crate) fn append_confirmed_after_live_validation(
        &self,
        store: &mut EventStore,
        confirmation: &HostConfirmation,
    ) -> Result<(), GenUiError> {
        self.validate_confirmation_identity(confirmation)?;
        let action_id = confirmation
            .identity
            .get("action_id")
            .and_then(Value::as_str)
            .ok_or(GenUiError::ConfirmationRequired)?;
        if confirmation
            .identity
            .get("payload_digest")
            .and_then(Value::as_str)
            != Some(digest_json(&confirmation.payload).as_str())
        {
            return Err(GenUiError::ConfirmationRequired);
        }
        self.validate_durable_current_action(store, action_id)?;
        let session_id = confirmation
            .identity
            .get("session_id")
            .and_then(Value::as_str)
            .ok_or(GenUiError::ConfirmationRequired)?;
        store
            .append_genui_lifecycle(
                session_id,
                EventKind::GenUiActionConfirmed,
                &confirmation.identity,
            )
            .map(|_| ())
            .map_err(event_error)
    }

    pub(crate) fn validate_confirmation_identity(
        &self,
        confirmation: &HostConfirmation,
    ) -> Result<&ResolvedActionBinding, GenUiError> {
        let session_id = confirmation
            .identity
            .get("session_id")
            .and_then(Value::as_str)
            .ok_or(GenUiError::ConfirmationRequired)?;
        let action_id = confirmation
            .identity
            .get("action_id")
            .and_then(Value::as_str)
            .ok_or(GenUiError::ConfirmationRequired)?;
        let binding = self
            .bindings
            .get(action_id)
            .ok_or(GenUiError::ConfirmationRequired)?;
        let expected = identity_payload(binding, None);
        let identity_matches = expected.as_object().is_some_and(|expected| {
            confirmation.identity.as_object().is_some_and(|actual| {
                expected
                    .iter()
                    .all(|(key, value)| actual.get(key) == Some(value))
            })
        });
        if binding.session_id != session_id
            || !identity_matches
            || confirmation
                .identity
                .get("payload_digest")
                .and_then(Value::as_str)
                .is_none()
        {
            return Err(GenUiError::ConfirmationRequired);
        }
        if !self.current_state_matches(binding) {
            return Err(GenUiError::ConfirmationRequired);
        }
        Ok(binding)
    }

    pub fn identity_for(&self, action_id: &str, payload: &Value) -> Result<Value, GenUiError> {
        let binding = self
            .bindings
            .get(action_id)
            .ok_or_else(|| GenUiError::UnauthorizedAction("unknown action ID".to_owned()))?;
        Ok(identity_payload(binding, Some(payload)))
    }

    fn current_state_matches(&self, binding: &ResolvedActionBinding) -> bool {
        self.current_states
            .get(&(binding.session_id.clone(), binding.principal.clone()))
            .is_some_and(|state| {
                state.generation == binding.state_generation
                    && state.digest == binding.state_digest
                    && state.authorization_context == binding.authorization_context
            })
    }

    pub fn validate_current_action(&self, action_id: &str) -> Result<(), GenUiError> {
        let binding = self
            .bindings
            .get(action_id)
            .ok_or_else(|| GenUiError::UnauthorizedAction("unknown action ID".to_owned()))?;
        if self.current_state_matches(binding) {
            Ok(())
        } else {
            Err(GenUiError::StaleAction(
                "trusted state changed immediately before execution".to_owned(),
            ))
        }
    }

    pub(crate) fn validate_durable_current_action(
        &self,
        store: &EventStore,
        action_id: &str,
    ) -> Result<(), GenUiError> {
        let binding = self
            .bindings
            .get(action_id)
            .ok_or_else(|| GenUiError::UnauthorizedAction("unknown action ID".to_owned()))?;
        let Some((generation, digest, authorization_context)) = store
            .genui_current_state(&binding.session_id, &binding.principal)
            .map_err(event_error)?
        else {
            return Err(GenUiError::StaleAction(
                "no durable trusted current state exists for this action".to_owned(),
            ));
        };
        if generation == binding.state_generation
            && digest == binding.state_digest
            && authorization_context == binding.authorization_context
        {
            Ok(())
        } else {
            Err(GenUiError::StaleAction(
                "durable trusted state changed immediately before execution".to_owned(),
            ))
        }
    }

    /// Validate an action against a freshly derived host workspace identity at
    /// the final transport boundary. The durable row and the in-memory binding
    /// must agree on generation, digest, and authorization context, and the
    /// just-read filesystem identity must equal that same trusted row.
    pub(crate) fn validate_fresh_workspace_identity(
        &self,
        store: &EventStore,
        action_id: &str,
        fresh_digest: &str,
        fresh_authorization_context: &str,
    ) -> Result<(), GenUiError> {
        let binding = self
            .bindings
            .get(action_id)
            .ok_or_else(|| GenUiError::UnauthorizedAction("unknown action ID".to_owned()))?;
        let Some((generation, digest, authorization_context)) = store
            .genui_current_state(&binding.session_id, &binding.principal)
            .map_err(event_error)?
        else {
            return Err(GenUiError::StaleAction(
                "no durable trusted current state exists for this action".to_owned(),
            ));
        };
        if generation != binding.state_generation
            || digest != binding.state_digest
            || authorization_context != binding.authorization_context
            || digest != fresh_digest
            || authorization_context != fresh_authorization_context
        {
            return Err(GenUiError::StaleAction(
                "current workspace state changed before MCP transport".to_owned(),
            ));
        }
        Ok(())
    }
}

impl Action {
    pub fn validate(&self, surface_id: &str, host: &HostCapabilities) -> Result<(), GenUiError> {
        validate_id("action", &self.id)?;
        if !self.id.starts_with("gui_action_") {
            return Err(GenUiError::InvalidSurface(
                "action IDs must be opaque host-issued IDs".to_owned(),
            ));
        }
        let label = normalize_action_label(&self.label)?;
        if label.trim().is_empty() || label.chars().count() > 512 {
            return Err(GenUiError::InvalidSurface(format!(
                "action {:?} has an empty or oversized label",
                self.id
            )));
        }
        if !host.supported_actions.contains(&self.kind) {
            return Err(GenUiError::UnsupportedAction(self.kind));
        }
        if surface_id.is_empty() {
            return Err(GenUiError::InvalidSurface(
                "action has no owning surface".to_owned(),
            ));
        }
        Ok(())
    }
}

fn identity_payload(binding: &ResolvedActionBinding, payload: Option<&Value>) -> Value {
    let mut object = Map::new();
    for (key, value) in [
        ("action_id", Value::String(binding.action_id.clone())),
        (
            "action_kind",
            serde_json::to_value(binding.action_kind).expect("ActionKind is serializable"),
        ),
        (
            "source_type",
            serde_json::to_value(binding.source_type).expect("ActionSourceType is serializable"),
        ),
        ("label_digest", Value::String(binding.label_digest.clone())),
        ("surface_id", Value::String(binding.surface_id.clone())),
        (
            "surface_digest",
            Value::String(binding.surface_digest.clone()),
        ),
        ("state_digest", Value::String(binding.state_digest.clone())),
        (
            "state_generation",
            Value::Number(binding.state_generation.into()),
        ),
        ("session_id", Value::String(binding.session_id.clone())),
        ("principal", Value::String(binding.principal.clone())),
        (
            "authorization_context",
            Value::String(binding.authorization_context.clone()),
        ),
        ("provider_id", Value::String(binding.provider_id.clone())),
        ("server_id", Value::String(binding.server_id.clone())),
        ("tool_name", Value::String(binding.tool_name.clone())),
        (
            "remote_tool_name",
            Value::String(binding.remote_tool_name.clone()),
        ),
        (
            "schema_digest",
            Value::String(binding.schema_digest.clone()),
        ),
        (
            "policy_version",
            Value::Number(binding.policy_version.into()),
        ),
        (
            "policy_digest",
            Value::String(binding.policy_digest.clone()),
        ),
        (
            "schema_version",
            Value::Number(crate::event::GENUI_EVENT_SCHEMA_VERSION.into()),
        ),
        (
            "requires_confirmation",
            Value::Bool(binding.requires_confirmation),
        ),
    ] {
        object.insert(key.to_owned(), value);
    }
    if let Some(payload) = payload {
        object.insert(
            "payload_digest".to_owned(),
            Value::String(digest_json(payload)),
        );
    }
    Value::Object(object)
}

fn event_error(error: EventError) -> GenUiError {
    GenUiError::EventStore(error.to_string())
}

fn validate_component(
    component: &Component,
    depth: usize,
    count: &mut usize,
    max_depth: usize,
    max_components: usize,
    ids: &mut BTreeSet<String>,
    host: &HostCapabilities,
) -> Result<(), GenUiError> {
    if depth > max_depth {
        return Err(GenUiError::InvalidSurface(format!(
            "component nesting exceeds bound {max_depth}"
        )));
    }
    *count = count.saturating_add(1);
    if *count > max_components {
        return Err(GenUiError::InvalidSurface(format!(
            "component count exceeds bound {max_components}"
        )));
    }
    validate_id("component", &component.id)?;
    if !ids.insert(component.id.clone()) {
        return Err(GenUiError::InvalidSurface(format!(
            "duplicate component ID {:?}",
            component.id
        )));
    }
    let name = component.kind.name();
    if !host.supported_components.contains(name)
        && host.unsupported_component_policy == UnsupportedComponentPolicy::Reject
    {
        return Err(GenUiError::UnsupportedComponent {
            component: name.to_owned(),
        });
    }
    validate_kind(&component.kind, host.max_columns())?;
    match &component.kind {
        ComponentKind::Stack { children } => {
            for child in children {
                validate_component(
                    child,
                    depth + 1,
                    count,
                    max_depth,
                    max_components,
                    ids,
                    host,
                )?;
            }
        }
        ComponentKind::Columns { columns } => {
            for column in columns {
                for child in column {
                    validate_component(
                        child,
                        depth + 1,
                        count,
                        max_depth,
                        max_components,
                        ids,
                        host,
                    )?;
                }
            }
        }
        _ => {}
    }
    Ok(())
}

impl HostCapabilities {
    fn max_columns(&self) -> usize {
        DEFAULT_MAX_COLUMNS
    }
}

fn validate_kind(kind: &ComponentKind, max_columns: usize) -> Result<(), GenUiError> {
    let mut text_bytes = 0usize;
    let mut add_text = |text: &str| {
        text_bytes = text_bytes.saturating_add(text.len());
        text_bytes <= DEFAULT_MAX_TEXT_BYTES
    };
    let valid = match kind {
        ComponentKind::Text { text } => add_text(text),
        ComponentKind::Markdown { markdown } => add_text(markdown),
        ComponentKind::Status { label, value, .. } => add_text(label) && add_text(value),
        ComponentKind::Progress {
            label,
            total,
            current,
        } => add_text(label) && total.is_none_or(|total| *current <= total),
        ComponentKind::Table { columns, rows } => {
            columns.len() <= max_columns
                && rows.len() <= DEFAULT_MAX_ROWS
                && rows
                    .iter()
                    .all(|row| row.len() == columns.len() && row.iter().all(|cell| add_text(cell)))
                && columns.iter().all(|column| add_text(column))
        }
        ComponentKind::KeyValue { entries } => {
            entries.len() <= DEFAULT_MAX_ROWS
                && entries
                    .iter()
                    .all(|(key, value)| add_text(key) && add_text(value))
        }
        ComponentKind::Diff { before, after } => add_text(before) && add_text(after),
        ComponentKind::TestResults { details, .. } => {
            details.len() <= DEFAULT_MAX_ROWS && details.iter().all(|detail| add_text(detail))
        }
        ComponentKind::Form { fields } => {
            fields.len() <= DEFAULT_MAX_ROWS
                && fields.iter().all(|field| {
                    validate_id("field", &field.id).is_ok()
                        && add_text(&field.label)
                        && field
                            .description
                            .as_ref()
                            .is_none_or(|description| add_text(description))
                        && field.choices.len() <= max_columns
                        && field.choices.iter().all(|choice| add_text(choice))
                        && (field.choice_values.is_empty()
                            || (field.choice_values.len() == field.choices.len()
                                && field
                                    .choice_values
                                    .iter()
                                    .all(|value| validate_value_size(value).is_ok())))
                        && field
                            .value
                            .as_ref()
                            .is_none_or(|value| validate_value_size(value).is_ok())
                        && field.constraints.keys().all(|key| {
                            matches!(
                                key.as_str(),
                                "minLength" | "maxLength" | "minimum" | "maximum" | "pattern"
                            )
                        })
                })
        }
        ComponentKind::Choice {
            label,
            options,
            selected,
        } => {
            add_text(label)
                && options.len() <= DEFAULT_MAX_ROWS
                && options
                    .iter()
                    .all(|option| add_text(&option.value) && add_text(&option.label))
                && selected
                    .as_ref()
                    .is_none_or(|value| options.iter().any(|option| &option.value == value))
        }
        ComponentKind::Evidence { title, items } => {
            add_text(title)
                && items.len() <= DEFAULT_MAX_ROWS
                && items
                    .iter()
                    .all(|item| add_text(&item.label) && add_text(&item.value))
        }
        ComponentKind::Timeline { entries } => {
            entries.len() <= DEFAULT_MAX_ROWS
                && entries
                    .iter()
                    .all(|entry| add_text(&entry.label) && add_text(&entry.detail))
        }
        ComponentKind::Stack { children } => children.len() <= DEFAULT_MAX_ROWS,
        ComponentKind::Columns { columns } => {
            columns.len() <= max_columns
                && columns
                    .iter()
                    .all(|column| column.len() <= DEFAULT_MAX_ROWS)
        }
    };
    if valid && text_bytes <= DEFAULT_MAX_TEXT_BYTES {
        Ok(())
    } else {
        Err(GenUiError::InvalidSurface(format!(
            "component payload exceeds bounded size or has invalid shape for {}",
            kind.name()
        )))
    }
}

fn validate_id(label: &str, value: &str) -> Result<(), GenUiError> {
    if value.is_empty()
        || value.len() > 128
        || value.bytes().any(|byte| {
            !(byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.' | b':'))
        })
    {
        Err(GenUiError::InvalidSurface(format!(
            "{label} ID {:?} is not a stable bounded identifier",
            value
        )))
    } else {
        Ok(())
    }
}

fn validate_digest(label: &str, value: &str) -> Result<(), GenUiError> {
    if value.len() != 64 || !value.bytes().all(|byte| byte.is_ascii_hexdigit()) {
        Err(GenUiError::InvalidSurface(format!(
            "{label} digest is invalid"
        )))
    } else {
        Ok(())
    }
}

fn is_bidi_format(character: char) -> bool {
    matches!(
        character,
        '\u{061c}'
            | '\u{200e}'
            | '\u{200f}'
            | '\u{200b}'
            | '\u{200c}'
            | '\u{200d}'
            | '\u{202a}'..='\u{202e}'
            | '\u{2060}'
            | '\u{2066}'..='\u{2069}'
            | '\u{feff}'
    )
}

fn is_zero_width_format(character: char) -> bool {
    matches!(
        character,
        '\u{200b}' | '\u{200c}' | '\u{200d}' | '\u{2028}' | '\u{2029}' | '\u{2060}' | '\u{feff}'
    )
}

/// Return the exact inert display representation bound into action identity.
/// Executable labels reject all controls, line/layout separators, and bidi
/// formatting characters rather than allowing the renderer and digest to
/// disagree.
fn normalize_action_label(label: &str) -> Result<String, GenUiError> {
    if label.chars().any(|character| {
        character.is_control()
            || is_bidi_format(character)
            || matches!(
                character,
                '\n' | '\r'
                    | '\t'
                    | '\u{200b}'
                    | '\u{200c}'
                    | '\u{200d}'
                    | '\u{2060}'
                    | '\u{feff}'
                    | '\u{2028}'
                    | '\u{2029}'
            )
    }) {
        return Err(GenUiError::InvalidSurface(
            "action label contains a control, newline, tab, or bidi formatting character"
                .to_owned(),
        ));
    }
    let display = sanitize_text(label);
    if display != label {
        return Err(GenUiError::InvalidSurface(
            "action label cannot be normalized safely".to_owned(),
        ));
    }
    Ok(display)
}

fn validate_value_size(value: &Value) -> Result<(), GenUiError> {
    let bytes =
        serde_json::to_vec(value).map_err(|error| GenUiError::InvalidSurface(error.to_string()))?;
    if bytes.len() > DEFAULT_MAX_TEXT_BYTES {
        Err(GenUiError::InvalidSurface(
            "value exceeds bounded size".to_owned(),
        ))
    } else {
        Ok(())
    }
}

fn digest_json<T: Serialize>(value: &T) -> String {
    let bytes = canonical_json_bytes(value).expect("typed GenUI values are serializable");
    sha256_hex(&bytes)
}

pub(crate) fn digest_value(value: &Value) -> String {
    digest_json(value)
}

/// Derive the GenUI authority identity from a trusted host snapshot. The
/// snapshot is supplied by `Agent`/the host transition, never by a model
/// action or a renderer caller. Keeping this derivation here gives discovery,
/// binding, and persistence one canonical digest format.
pub(crate) fn derive_host_state_identity(
    session_id: &str,
    principal: &str,
    host_snapshot: &Value,
) -> (String, String) {
    let digest = digest_json(&serde_json::json!({
        "schema": "falsegreen.agent.genui.host-state.v1",
        "session_id": session_id,
        "principal": principal,
        "snapshot": host_snapshot,
    }));
    let authorization_context = format!("agent-session:{session_id}:principal:{principal}");
    (digest, authorization_context)
}

/// Derive the execution authority identity from the actual current workspace.
/// This is deliberately the same helper used when the trusted Agent advances
/// durable GenUI state and when the transport gate rechecks it.  No cached or
/// caller-provided workspace fingerprint participates in this identity.
pub fn derive_host_workspace_state_identity(
    session_id: &str,
    principal: &str,
    workspace_state: &WorkspaceState,
) -> (String, String) {
    derive_host_state_identity(
        session_id,
        principal,
        &serde_json::json!({"workspace": workspace_state}),
    )
}

/// Canonical identity digest for an MCP input schema. This is public so the
/// discovery catalog and GenUI adapter cannot accidentally use different
/// serialization rules.
#[must_use]
pub fn mcp_schema_digest(schema: &Value) -> String {
    // MCP schema identity must remain total even for hostile Values assembled
    // by a caller rather than parsed from bounded input. The iterative encoder
    // never recurses, so a 5,000-level annotation cannot overflow the stack.
    match canonical_json_bytes_value_iterative(schema) {
        Ok(bytes) => sha256_hex(&bytes),
        Err(_) => sha256_hex(b"falsegreen.agent.genui.mcp-schema.invalid-v2"),
    }
}

fn canonical_json_bytes_value_iterative(value: &Value) -> Result<Vec<u8>, serde_json::Error> {
    enum Task<'a> {
        Value(&'a Value),
        Key(&'a str),
        Raw(&'static [u8]),
    }

    let mut output = Vec::new();
    let mut tasks = vec![Task::Value(value)];
    while let Some(task) = tasks.pop() {
        match task {
            Task::Raw(bytes) => output.extend_from_slice(bytes),
            Task::Key(key) => serde_json::to_writer(&mut output, key)?,
            Task::Value(value) => match value {
                Value::Null => output.extend_from_slice(b"null"),
                Value::Bool(value) => {
                    output.extend_from_slice(if *value { b"true" } else { b"false" })
                }
                Value::Number(value) => serde_json::to_writer(&mut output, value)?,
                Value::String(value) => serde_json::to_writer(&mut output, value)?,
                Value::Array(items) => {
                    output.push(b'[');
                    tasks.push(Task::Raw(b"]"));
                    for (index, item) in items.iter().enumerate().rev() {
                        if index + 1 < items.len() {
                            tasks.push(Task::Raw(b","));
                        }
                        tasks.push(Task::Value(item));
                    }
                }
                Value::Object(object) => {
                    let mut entries = object
                        .iter()
                        .map(|(key, value)| (key.as_str(), value))
                        .collect::<Vec<_>>();
                    entries.sort_unstable_by(|left, right| left.0.cmp(right.0));
                    output.push(b'{');
                    tasks.push(Task::Raw(b"}"));
                    for (index, (key, value)) in entries.iter().enumerate().rev() {
                        if index + 1 < entries.len() {
                            tasks.push(Task::Raw(b","));
                        }
                        tasks.push(Task::Value(value));
                        tasks.push(Task::Raw(b":"));
                        tasks.push(Task::Key(key));
                    }
                }
            },
        }
    }
    Ok(output)
}

fn canonical_json_bytes<T: Serialize>(value: &T) -> Result<Vec<u8>, serde_json::Error> {
    let value = serde_json::to_value(value)?;
    serde_json::to_vec(&canonicalize_json(value))
}

fn canonicalize_json(value: Value) -> Value {
    match value {
        Value::Object(object) => {
            let mut canonical = Map::new();
            for (key, value) in object {
                canonical.insert(key, canonicalize_json(value));
            }
            // serde_json::Map preserves insertion order by default. Rebuild
            // through a BTreeMap so identity is independent of input order.
            let mut sorted = BTreeMap::new();
            for (key, value) in canonical {
                sorted.insert(key, value);
            }
            Value::Object(sorted.into_iter().collect())
        }
        Value::Array(items) => Value::Array(items.into_iter().map(canonicalize_json).collect()),
        other => other,
    }
}

fn sha256_hex(bytes: &[u8]) -> String {
    format!("{:x}", Sha256::digest(bytes))
}

/// Remove ANSI/OSC/CSI and other terminal control bytes from model/tool text.
/// Newlines are retained as layout data; tabs and all other controls are
/// replaced with a visible space so terminal display width stays bounded. No
/// escape sequence is emitted by this code.
#[must_use]
pub fn sanitize_text(input: &str) -> String {
    let mut output = String::with_capacity(input.len());
    let mut chars = input.chars().peekable();
    while let Some(ch) = chars.next() {
        if ch == '\u{1b}' {
            if chars.peek() == Some(&'[') {
                chars.next();
                for next in chars.by_ref() {
                    if ('@'..='~').contains(&next) {
                        break;
                    }
                }
            } else if chars.peek() == Some(&']') {
                chars.next();
                let mut previous_escape = false;
                for next in chars.by_ref() {
                    if next == '\u{7}' {
                        break;
                    }
                    if previous_escape && next == '\\' {
                        break;
                    }
                    previous_escape = next == '\u{1b}';
                }
            } else if matches!(chars.peek(), Some('P' | '^' | '_')) {
                // DCS/PM/APC are string control sequences terminated by ST
                // (ESC \) or BEL. Drop the complete sequence, not merely
                // its introducer, so hostile payload text cannot surface.
                chars.next();
                let mut previous_escape = false;
                for next in chars.by_ref() {
                    if next == '\u{7}' {
                        break;
                    }
                    if previous_escape && next == '\\' {
                        break;
                    }
                    previous_escape = next == '\u{1b}';
                }
            } else {
                let _ = chars.next();
            }
        } else if ch == '\n' {
            output.push(ch);
        } else if ch.is_control() || is_bidi_format(ch) || is_zero_width_format(ch) {
            output.push(' ');
        } else {
            output.push(ch);
        }
    }
    output
}

/// Sanitize metadata that is rendered inline with form fields or action
/// affordances. All line/layout controls, bidi formatting, zero-width
/// characters, and terminal controls become ordinary spaces; whitespace is
/// collapsed and trimmed so the result is always one inert display line.
#[must_use]
pub fn sanitize_single_line_metadata(input: &str) -> String {
    let sanitized = sanitize_text(input);
    let mut output = String::with_capacity(sanitized.len());
    let mut pending_space = false;
    for character in sanitized.chars() {
        if character.is_whitespace()
            || character.is_control()
            || is_bidi_format(character)
            || is_zero_width_format(character)
        {
            pending_space = true;
            continue;
        }
        if pending_space && !output.is_empty() {
            output.push(' ');
        }
        output.push(character);
        pending_space = false;
    }
    output
}

/// Render using the exact capability set negotiated by the trusted host.
/// This low-level renderer is crate-private; production callers must use the
/// catalog-aware admission path below so degraded subtrees revoke authority.
#[allow(dead_code)]
pub(crate) fn render_surface_with_capabilities(
    surface: &Surface,
    capabilities: &NegotiatedCapabilities,
) -> Result<String, GenUiError> {
    let host = HostCapabilities {
        protocol: capabilities.protocol,
        supported_components: capabilities.supported_components.clone(),
        supported_actions: capabilities.supported_actions.clone(),
        unsupported_component_policy: capabilities.unsupported_component_policy,
        terminal_width: capabilities.terminal_width.max(1),
        ..HostCapabilities::default()
    };
    surface.validate_shape(&host)?;
    let mut lines = Vec::new();
    let has_unsupported_component =
        !unsupported_component_ids(&surface.root, &host.supported_components).is_empty();
    render_component(&surface.root, &host.supported_components, &mut lines);
    // A placeholder is display-only. Never put executable action affordances
    // beside a degraded component tree, and never display an action kind that
    // this negotiated host did not admit.
    if !has_unsupported_component {
        for action in &surface.actions {
            if !capabilities.supported_actions.contains(&action.kind) {
                continue;
            }
            let label = normalize_action_label(&action.label)
                .expect("validated action labels have a canonical display representation");
            lines.push(format!("[{}] {label}", action.id));
        }
    }
    Ok(lines
        .into_iter()
        .flat_map(|line| wrap_line(&line, host.terminal_width))
        .collect::<Vec<_>>()
        .join("\n"))
}

/// Renderer/authority integration for callers that own the host catalog.
/// Admission revokes degraded-surface actions before producing display text.
#[allow(dead_code)]
pub(crate) fn render_surface_with_capabilities_and_catalog(
    surface: &Surface,
    capabilities: &NegotiatedCapabilities,
    catalog: &mut ActionCatalog,
) -> Result<String, GenUiError> {
    catalog.admit_rendered_surface(surface, capabilities)?;
    let host = HostCapabilities {
        protocol: capabilities.protocol,
        supported_components: capabilities.supported_components.clone(),
        supported_actions: capabilities.supported_actions.clone(),
        unsupported_component_policy: capabilities.unsupported_component_policy,
        terminal_width: capabilities.terminal_width.max(1),
        ..HostCapabilities::default()
    };
    surface.validate_shape(&host)?;
    let mut lines = Vec::new();
    render_component(&surface.root, &host.supported_components, &mut lines);
    for action in &surface.actions {
        if !capabilities.supported_actions.contains(&action.kind)
            || catalog.resolve(&action.id).is_none()
        {
            continue;
        }
        let label = normalize_action_label(&action.label)
            .expect("validated action labels have a canonical display representation");
        lines.push(format!("[{}] {label}", action.id));
    }
    Ok(lines
        .into_iter()
        .flat_map(|line| wrap_line(&line, host.terminal_width))
        .collect::<Vec<_>>()
        .join("\n"))
}

/// Canonical renderer entry point for durable GenUI surfaces. Admission reads
/// current authority from the EventStore before any executable affordance is
/// included in the rendered output.
pub fn render_surface_with_capabilities_and_catalog_with_store(
    surface: &Surface,
    capabilities: &NegotiatedCapabilities,
    catalog: &mut ActionCatalog,
    store: &EventStore,
) -> Result<String, GenUiError> {
    catalog.admit_rendered_surface_with_store(surface, capabilities, store)?;
    let host = HostCapabilities {
        protocol: capabilities.protocol,
        supported_components: capabilities.supported_components.clone(),
        supported_actions: capabilities.supported_actions.clone(),
        unsupported_component_policy: capabilities.unsupported_component_policy,
        terminal_width: capabilities.terminal_width.max(1),
        ..HostCapabilities::default()
    };
    surface.validate_shape(&host)?;
    let mut lines = Vec::new();
    render_component(&surface.root, &host.supported_components, &mut lines);
    for action in &surface.actions {
        if !capabilities.supported_actions.contains(&action.kind)
            || catalog.resolve(&action.id).is_none()
        {
            continue;
        }
        let label = normalize_action_label(&action.label)
            .expect("validated action labels have a canonical display representation");
        lines.push(format!("[{}] {label}", action.id));
    }
    Ok(lines
        .into_iter()
        .flat_map(|line| wrap_line(&line, host.terminal_width))
        .collect::<Vec<_>>()
        .join("\n"))
}

fn unsupported_component_ids(
    component: &Component,
    supported: &BTreeSet<String>,
) -> BTreeSet<String> {
    let mut output = BTreeSet::new();
    collect_unsupported_component_ids(component, supported, &mut output);
    output
}

fn collect_unsupported_component_ids(
    component: &Component,
    supported: &BTreeSet<String>,
    output: &mut BTreeSet<String>,
) {
    if !supported.contains(component.kind.name()) {
        output.insert(component.id.clone());
    }
    match &component.kind {
        ComponentKind::Stack { children } => {
            for child in children {
                collect_unsupported_component_ids(child, supported, output);
            }
        }
        ComponentKind::Columns { columns } => {
            for child in columns.iter().flatten() {
                collect_unsupported_component_ids(child, supported, output);
            }
        }
        _ => {}
    }
}

fn component_contains_id(component: &Component, ancestor: &str, target: &str) -> bool {
    if component.id == ancestor {
        return component.id == target || component_contains_descendant(component, target);
    }
    match &component.kind {
        ComponentKind::Stack { children } => children
            .iter()
            .any(|child| component_contains_id(child, ancestor, target)),
        ComponentKind::Columns { columns } => columns
            .iter()
            .flatten()
            .any(|child| component_contains_id(child, ancestor, target)),
        _ => false,
    }
}

fn component_contains_descendant(component: &Component, target: &str) -> bool {
    match &component.kind {
        ComponentKind::Stack { children } => children
            .iter()
            .any(|child| child.id == target || component_contains_descendant(child, target)),
        ComponentKind::Columns { columns } => columns
            .iter()
            .flatten()
            .any(|child| child.id == target || component_contains_descendant(child, target)),
        _ => false,
    }
}

#[must_use]
pub fn default_negotiated_capabilities(width: usize) -> NegotiatedCapabilities {
    let host = HostCapabilities {
        terminal_width: width.max(1),
        ..HostCapabilities::default()
    };
    negotiate(&[ProtocolVersion::current()], &host)
        .expect("current protocol must negotiate with the default host")
}

fn render_component(component: &Component, supported: &BTreeSet<String>, lines: &mut Vec<String>) {
    if !supported.contains(component.kind.name()) {
        lines.push(format!(
            "[unsupported component: {}]",
            component.kind.name()
        ));
        return;
    }
    match &component.kind {
        ComponentKind::Text { text } | ComponentKind::Markdown { markdown: text } => {
            lines.extend(sanitize_text(text).lines().map(str::to_owned));
        }
        ComponentKind::Status { label, value, .. } => {
            lines.push(format!(
                "{}: {}",
                sanitize_text(label),
                sanitize_text(value)
            ));
        }
        ComponentKind::Progress {
            label,
            current,
            total,
        } => {
            let progress = total.map_or_else(
                || "indeterminate".to_owned(),
                |total| format!("{current}/{total}"),
            );
            lines.push(format!("{}: {progress}", sanitize_text(label)));
        }
        ComponentKind::Table { columns, rows } => {
            lines.push(
                columns
                    .iter()
                    .map(|column| sanitize_text(column))
                    .collect::<Vec<_>>()
                    .join(" | "),
            );
            for row in rows {
                lines.push(
                    row.iter()
                        .map(|cell| sanitize_text(cell))
                        .collect::<Vec<_>>()
                        .join(" | "),
                );
            }
        }
        ComponentKind::KeyValue { entries } => {
            for (key, value) in entries {
                lines.push(format!("{}: {}", sanitize_text(key), sanitize_text(value)));
            }
        }
        ComponentKind::Diff { before, after } => {
            lines.push(format!("- {}", sanitize_text(before)));
            lines.push(format!("+ {}", sanitize_text(after)));
        }
        ComponentKind::TestResults {
            passed,
            failed,
            skipped,
            details,
        } => {
            lines.push(format!(
                "tests: {passed} passed, {failed} failed, {skipped} skipped"
            ));
            lines.extend(
                details
                    .iter()
                    .map(|detail| format!("  {}", sanitize_text(detail))),
            );
        }
        ComponentKind::Form { fields } => {
            for field in fields {
                let value = field.value.as_ref().map_or_else(
                    || "".to_owned(),
                    |value| sanitize_single_line_metadata(&value.to_string()),
                );
                lines.push(format!(
                    "{}{}: {}",
                    if field.required { "*" } else { "" },
                    sanitize_text(&field.label),
                    value
                ));
            }
        }
        ComponentKind::Choice {
            label,
            options,
            selected,
        } => {
            lines.push(format!("{}:", sanitize_text(label)));
            for option in options {
                let marker = if selected.as_ref() == Some(&option.value) {
                    "*"
                } else {
                    " "
                };
                lines.push(format!("  [{marker}] {}", sanitize_text(&option.label)));
            }
        }
        ComponentKind::Evidence { title, items } => {
            lines.push(sanitize_text(title));
            for item in items {
                lines.push(format!(
                    "  {}: {}",
                    sanitize_text(&item.label),
                    sanitize_text(&item.value)
                ));
            }
        }
        ComponentKind::Timeline { entries } => {
            for entry in entries {
                lines.push(format!(
                    "{:?} {} — {}",
                    entry.state,
                    sanitize_text(&entry.label),
                    sanitize_text(&entry.detail)
                ));
            }
        }
        ComponentKind::Stack { children } => {
            for child in children {
                render_component(child, supported, lines);
            }
        }
        ComponentKind::Columns { columns } => {
            let mut rendered = Vec::new();
            for column in columns {
                let mut column_lines = Vec::new();
                for child in column {
                    render_component(child, supported, &mut column_lines);
                }
                rendered.push(column_lines);
            }
            let rows = rendered.iter().map(Vec::len).max().unwrap_or(0);
            for row in 0..rows {
                lines.push(
                    rendered
                        .iter()
                        .map(|column| column.get(row).cloned().unwrap_or_default())
                        .collect::<Vec<_>>()
                        .join(" | "),
                );
            }
        }
    }
}

fn wrap_line(line: &str, width: usize) -> Vec<String> {
    if line.is_empty() {
        return vec![String::new()];
    }
    let width = width.max(1);
    let mut output = Vec::new();
    let mut current = String::new();
    let mut current_width = 0usize;
    for character in line.chars() {
        let character_width = UnicodeWidthChar::width(character).unwrap_or(0);
        if character_width > 0 && current_width + character_width > width {
            output.push(std::mem::take(&mut current));
            current_width = 0;
        }
        current.push(character);
        current_width = current_width.saturating_add(character_width);
    }
    if !current.is_empty() || output.is_empty() {
        output.push(current);
    }
    output
}

/// The deliberately small, typed MCP schema language accepted by the V1
/// adapter. Raw JSON is parsed once into this representation and is never
/// reinterpreted by the renderer or submission path.
pub const MCP_SCHEMA_ADAPTER_ID: &str = "falsegreen.agent.genui.mcp-schema.v1";
pub const MCP_SCHEMA_MAX_BYTES: usize = 4 * 1024 * 1024;
pub const MCP_SCHEMA_MAX_FIELDS: usize = 256;
pub const MCP_SCHEMA_MAX_ENUM_VALUES: usize = DEFAULT_MAX_COLUMNS;
pub const MCP_SCHEMA_MAX_STRING_LENGTH: u64 = 1_000_000;
/// Supported G3 schemas are intentionally shallow: an object root contains
/// scalar property definitions and no recursive schema constructs. This bound
/// is global and is checked before any recursive serialization/canonicalization.
pub const MCP_SCHEMA_MAX_JSON_DEPTH: usize = 64;
/// Bound total JSON nodes so large annotation trees cannot amplify parsing or
/// digest work even when they stay within the depth bound. `examples` is
/// rejected separately, but this also covers unknown annotation structures.
pub const MCP_SCHEMA_MAX_JSON_NODES: usize = 16_384;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum McpSchemaDialect {
    Draft7,
    Draft202012,
}

impl McpSchemaDialect {
    #[must_use]
    pub const fn uri(self) -> &'static str {
        match self {
            Self::Draft7 => "http://json-schema.org/draft-07/schema#",
            Self::Draft202012 => "https://json-schema.org/draft/2020-12/schema",
        }
    }

    fn parse(value: &Value) -> Result<Self, GenUiError> {
        let uri = value
            .as_str()
            .ok_or_else(|| unsupported_schema("unsupported_dialect", "$schema must be a string"))?;
        match uri {
            "http://json-schema.org/draft-07/schema#" => Ok(Self::Draft7),
            "https://json-schema.org/draft/2020-12/schema" => Ok(Self::Draft202012),
            _ => Err(unsupported_schema(
                "unsupported_dialect",
                format!("unsupported JSON-Schema dialect {uri:?}"),
            )),
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum McpSchemaType {
    String,
    Integer,
    Boolean,
}

impl McpSchemaType {
    fn parse(name: &str, property: &str) -> Result<Self, GenUiError> {
        match name {
            "string" => Ok(Self::String),
            "integer" => Ok(Self::Integer),
            "boolean" => Ok(Self::Boolean),
            "number" => Err(unsupported_schema(
                "unsupported_type",
                format!(
                    "property {property:?} uses number; exact decimal semantics are not enabled"
                ),
            )),
            "array" => Err(unsupported_schema(
                "unsupported_nested_array",
                format!("property {property:?} uses an array"),
            )),
            "object" => Err(unsupported_schema(
                "unsupported_nested_object",
                format!("property {property:?} uses a nested object"),
            )),
            other => Err(unsupported_schema(
                "unsupported_type",
                format!("property {property:?} uses unsupported type {other:?}"),
            )),
        }
    }

    fn field_type(self) -> FieldType {
        match self {
            Self::String => FieldType::String,
            Self::Integer => FieldType::Integer,
            Self::Boolean => FieldType::Boolean,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum McpScalarValue {
    String(String),
    Integer(i64),
    UnsignedInteger(u64),
    Boolean(bool),
}

impl McpScalarValue {
    fn parse(value: &Value, expected: McpSchemaType, property: &str) -> Result<Self, GenUiError> {
        let parsed = match expected {
            McpSchemaType::String => value.as_str().map(|value| Self::String(value.to_owned())),
            McpSchemaType::Integer => value
                .as_i64()
                .map(Self::Integer)
                .or_else(|| value.as_u64().map(Self::UnsignedInteger)),
            McpSchemaType::Boolean => value.as_bool().map(Self::Boolean),
        };
        parsed.ok_or_else(|| {
            unsupported_schema(
                "enum_type_mismatch",
                format!("property {property:?} has a value of the wrong type"),
            )
        })
    }

    fn from_submission(value: &Value, expected: McpSchemaType) -> Option<Self> {
        match expected {
            McpSchemaType::String => value.as_str().map(|value| Self::String(value.to_owned())),
            McpSchemaType::Integer => value
                .as_i64()
                .map(Self::Integer)
                .or_else(|| value.as_u64().map(Self::UnsignedInteger)),
            McpSchemaType::Boolean => value.as_bool().map(Self::Boolean),
        }
    }

    fn to_json(&self) -> Value {
        match self {
            Self::String(value) => Value::String(value.clone()),
            Self::Integer(value) => Value::Number((*value).into()),
            Self::UnsignedInteger(value) => Value::Number((*value).into()),
            Self::Boolean(value) => Value::Bool(*value),
        }
    }

    fn display(&self) -> String {
        sanitize_single_line_metadata(&match self {
            Self::String(value) => value.clone(),
            Self::Integer(value) => value.to_string(),
            Self::UnsignedInteger(value) => value.to_string(),
            Self::Boolean(value) => value.to_string(),
        })
    }

    fn integer(&self) -> Option<i128> {
        match self {
            Self::Integer(value) => Some(i128::from(*value)),
            Self::UnsignedInteger(value) => Some(i128::from(*value)),
            _ => None,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct McpSchemaField {
    pub name: String,
    pub schema_type: McpSchemaType,
    pub required: bool,
    pub enum_values: Vec<McpScalarValue>,
    pub title: Option<String>,
    pub description: Option<String>,
    pub default: Option<McpScalarValue>,
    pub min_length: Option<u64>,
    pub max_length: Option<u64>,
    pub minimum: Option<i128>,
    pub maximum: Option<i128>,
}

impl McpSchemaField {
    fn validate_value(&self, value: &Value) -> Result<(), GenUiError> {
        let parsed = McpScalarValue::from_submission(value, self.schema_type).ok_or_else(|| {
            GenUiError::InvalidMcpSubmission(format!("field {:?} has the wrong type", self.name))
        })?;
        if !self.enum_values.is_empty() && !self.enum_values.contains(&parsed) {
            return Err(GenUiError::InvalidMcpSubmission(format!(
                "field {:?} is outside its enum",
                self.name
            )));
        }
        if let Some(number) = parsed.integer() {
            if self.minimum.is_some_and(|minimum| number < minimum) {
                return Err(GenUiError::InvalidMcpSubmission(format!(
                    "field {:?} is below its minimum",
                    self.name
                )));
            }
            if self.maximum.is_some_and(|maximum| number > maximum) {
                return Err(GenUiError::InvalidMcpSubmission(format!(
                    "field {:?} exceeds its maximum",
                    self.name
                )));
            }
        }
        if let Some(text) = value.as_str() {
            if self
                .min_length
                .is_some_and(|minimum| text.chars().count() < minimum as usize)
            {
                return Err(GenUiError::InvalidMcpSubmission(format!(
                    "field {:?} is shorter than minLength",
                    self.name
                )));
            }
            if self
                .max_length
                .is_some_and(|maximum| text.chars().count() > maximum as usize)
            {
                return Err(GenUiError::InvalidMcpSubmission(format!(
                    "field {:?} is longer than maxLength",
                    self.name
                )));
            }
        }
        Ok(())
    }

    fn validate_default(&self, value: &Value) -> Result<(), GenUiError> {
        McpScalarValue::parse(value, self.schema_type, &self.name).map_err(|_| {
            unsupported_schema(
                "malformed_default",
                format!("property {:?} default has the wrong type", self.name),
            )
        })?;
        self.validate_value(value).map_err(|error| match error {
            GenUiError::InvalidMcpSubmission(message) => {
                unsupported_schema("malformed_default", message)
            }
            other => other,
        })
    }

    fn as_form_field(&self) -> FormField {
        let choices = self
            .enum_values
            .iter()
            .map(McpScalarValue::display)
            .collect::<Vec<_>>();
        let choice_values = self
            .enum_values
            .iter()
            .map(McpScalarValue::to_json)
            .collect::<Vec<_>>();
        let mut constraints = BTreeMap::new();
        if let Some(value) = self.min_length {
            constraints.insert("minLength".to_owned(), Value::Number(value.into()));
        }
        if let Some(value) = self.max_length {
            constraints.insert("maxLength".to_owned(), Value::Number(value.into()));
        }
        if let Some(value) = self.minimum.and_then(i128_to_json_number) {
            constraints.insert("minimum".to_owned(), Value::Number(value));
        }
        if let Some(value) = self.maximum.and_then(i128_to_json_number) {
            constraints.insert("maximum".to_owned(), Value::Number(value));
        }
        FormField {
            id: self.name.clone(),
            label: self
                .title
                .as_deref()
                .filter(|title| !title.is_empty())
                .unwrap_or(&self.name)
                .to_owned(),
            field_type: self.schema_type.field_type(),
            required: self.required,
            description: self.description.clone(),
            value: self.default.as_ref().map(McpScalarValue::to_json),
            choices,
            choice_values,
            constraints,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct McpSchemaIr {
    pub adapter: &'static str,
    pub dialect: Option<McpSchemaDialect>,
    pub source_digest: String,
    pub additional_properties: bool,
    pub title: Option<String>,
    pub description: Option<String>,
    pub fields: Vec<McpSchemaField>,
}

impl McpSchemaIr {
    /// Parse an MCP input schema into a typed, bounded representation. The
    /// source digest is the identity of the exact raw schema and is retained
    /// for the host binding; it is never recomputed from the form projection.
    pub fn parse(schema: &Value) -> Result<Self, GenUiError> {
        parse_mcp_schema(schema)
    }

    #[must_use]
    pub fn source_digest(&self) -> &str {
        &self.source_digest
    }

    #[must_use]
    pub fn dialect_uri(&self) -> Option<&'static str> {
        self.dialect.map(McpSchemaDialect::uri)
    }

    #[must_use]
    pub fn form_fields(&self) -> Vec<FormField> {
        self.fields
            .iter()
            .map(McpSchemaField::as_form_field)
            .collect()
    }

    /// Validate a JSON object without coercing values or applying defaults.
    /// An omitted optional field remains omitted; JSON null is not accepted
    /// because nullable unions are outside this exact V1 dialect subset.
    pub fn validate_submission(&self, arguments: &Value) -> Result<(), GenUiError> {
        let args = arguments.as_object().ok_or_else(|| {
            GenUiError::InvalidMcpSubmission("arguments must be an object".to_owned())
        })?;
        for field in &self.fields {
            if field.required && !args.contains_key(&field.name) {
                return Err(GenUiError::InvalidMcpSubmission(format!(
                    "required field {:?} is missing",
                    field.name
                )));
            }
        }
        for (name, value) in args {
            let Some(field) = self.fields.iter().find(|field| field.name == *name) else {
                return Err(GenUiError::InvalidMcpSubmission(
                    "unknown field is not permitted by the original schema".to_owned(),
                ));
            };
            field.validate_value(value)?;
        }
        Ok(())
    }

    fn validate_form_projection(&self) -> Result<(), GenUiError> {
        let form = ComponentKind::Form {
            fields: self.form_fields(),
        };
        validate_kind(&form, DEFAULT_MAX_COLUMNS).map_err(|error| {
            unsupported_schema(
                "surface_limit",
                format!("adapted form cannot be constructed: {error}"),
            )
        })
    }

    /// Reconstruct the exact object represented by submitted UI values. The
    /// caller supplies only explicitly submitted values, so defaults are not
    /// silently inserted and no string-to-number/boolean guessing occurs.
    pub fn reconstruct_payload(
        &self,
        values: &BTreeMap<String, Value>,
    ) -> Result<Value, GenUiError> {
        let arguments = Value::Object(
            values
                .iter()
                .map(|(name, value)| (name.clone(), value.clone()))
                .collect(),
        );
        self.validate_submission(&arguments)?;
        Ok(arguments)
    }
}

/// Parse an MCP schema into the trusted normalized IR.
pub fn adapt_mcp_schema(schema: &Value) -> Result<McpSchemaIr, GenUiError> {
    McpSchemaIr::parse(schema)
}

/// Reconstruct a payload through the same IR used by trusted form rendering.
pub fn reconstruct_mcp_payload(
    schema: &Value,
    values: &BTreeMap<String, Value>,
) -> Result<Value, GenUiError> {
    McpSchemaIr::parse(schema)?.reconstruct_payload(values)
}

/// Construct a typed form surface from an MCP tool's original input schema.
/// The resulting action has only an opaque presentation ID; executable tool
/// and schema identity are retained privately by the host catalog.
pub fn mcp_tool_surface(
    surface_id: impl Into<String>,
    tool_name: impl Into<String>,
    schema: &Value,
    state_digest: impl Into<String>,
) -> Result<Surface, GenUiError> {
    let surface_id = surface_id.into();
    let tool_name = tool_name.into();
    validate_id("tool", &tool_name)?;
    let ir = McpSchemaIr::parse(schema)?;
    let root = Component {
        id: "mcp-form".to_owned(),
        kind: ComponentKind::Form {
            fields: ir.form_fields(),
        },
    };
    let mut surface = Surface::new(surface_id, root);
    surface.actions.push(Action {
        id: ActionCatalog::new_action_id(),
        label: "Submit".to_owned(),
        kind: ActionKind::McpTool,
        state_digest: state_digest.into(),
    });
    surface.validate_shape(&HostCapabilities::default())?;
    Ok(surface)
}

pub fn validate_mcp_submission(schema: &Value, arguments: &Value) -> Result<(), GenUiError> {
    McpSchemaIr::parse(schema)?.validate_submission(arguments)
}

fn validate_schema_json_bounds(schema: &Value) -> Result<(), GenUiError> {
    let mut pending = vec![(schema, 0usize)];
    let mut nodes = 0usize;
    while let Some((value, depth)) = pending.pop() {
        if depth > MCP_SCHEMA_MAX_JSON_DEPTH {
            return Err(unsupported_schema(
                "schema_depth_exceeded",
                format!(
                    "JSON nesting depth {depth} exceeds the global bound {MCP_SCHEMA_MAX_JSON_DEPTH}"
                ),
            ));
        }
        nodes = nodes.saturating_add(1);
        if nodes > MCP_SCHEMA_MAX_JSON_NODES {
            return Err(unsupported_schema(
                "schema_complexity_exceeded",
                format!("JSON node count exceeds the global bound {MCP_SCHEMA_MAX_JSON_NODES}"),
            ));
        }
        match value {
            Value::Array(items) => pending.extend(items.iter().map(|item| (item, depth + 1))),
            Value::Object(object) => pending.extend(object.values().map(|item| (item, depth + 1))),
            Value::Null | Value::Bool(_) | Value::Number(_) | Value::String(_) => {}
        }
    }
    Ok(())
}

fn parse_mcp_schema(schema: &Value) -> Result<McpSchemaIr, GenUiError> {
    validate_schema_json_bounds(schema)?;
    validate_schema_serialized_size(schema)?;
    let object = schema
        .as_object()
        .ok_or_else(|| unsupported_schema("unsupported_type", "input schema must be an object"))?;
    let allowed_root = [
        "type",
        "properties",
        "required",
        "additionalProperties",
        "title",
        "description",
        "default",
        "examples",
        "$schema",
        "$id",
    ];
    reject_unknown_schema_keywords(object, &allowed_root, "root")?;
    if object.get("type").and_then(Value::as_str) != Some("object") {
        return Err(unsupported_schema(
            "unsupported_type",
            "root schema must have type object",
        ));
    }
    match object.get("additionalProperties") {
        Some(Value::Bool(false)) => {}
        Some(Value::Bool(true)) => {
            return Err(unsupported_schema(
                "additional_properties",
                "additionalProperties:true is outside the FalseGreen schema subset",
            ));
        }
        Some(_) => {
            return Err(unsupported_schema(
                "additional_properties",
                "additionalProperties must be exactly false",
            ));
        }
        None => {
            return Err(unsupported_schema(
                "additional_properties",
                "additionalProperties must be explicitly false",
            ));
        }
    }
    let dialect = object
        .get("$schema")
        .map(McpSchemaDialect::parse)
        .transpose()?;
    let title = parse_metadata(object, "title", "root")?;
    let description = parse_metadata(object, "description", "root")?;
    if object.contains_key("$id") {
        return Err(unsupported_schema(
            "unsupported_keyword",
            "$id is not supported by the G3 adapter",
        ));
    }
    if object.contains_key("examples") {
        return Err(unsupported_schema(
            "unsupported_annotation",
            "root examples are not supported by the G3 adapter",
        ));
    }
    let required = parse_required_fields(object)?;
    let properties = match object.get("properties") {
        Some(Value::Object(properties)) => properties,
        Some(_) => {
            return Err(unsupported_schema(
                "malformed_schema",
                "properties must be an object",
            ));
        }
        None => &Map::new(),
    };
    if properties.len() > MCP_SCHEMA_MAX_FIELDS {
        return Err(unsupported_schema(
            "schema_too_large",
            format!("property count exceeds {MCP_SCHEMA_MAX_FIELDS}"),
        ));
    }
    for name in &required {
        if !properties.contains_key(name) {
            return Err(unsupported_schema(
                "required_unknown_field",
                format!("required field {name:?} is not declared in properties"),
            ));
        }
    }
    let mut fields = Vec::with_capacity(properties.len());
    for (name, property) in properties {
        if validate_id("field", name).is_err() {
            return Err(unsupported_schema(
                "unsupported_property_name",
                format!("property name {name:?} cannot be represented as a trusted field ID"),
            ));
        }
        let property = property.as_object().ok_or_else(|| {
            unsupported_schema(
                "malformed_schema",
                format!("property {name:?} is not an object"),
            )
        })?;
        fields.push(parse_schema_field(name, property, required.contains(name))?);
    }
    let ir = McpSchemaIr {
        adapter: MCP_SCHEMA_ADAPTER_ID,
        dialect,
        source_digest: mcp_schema_digest(schema),
        additional_properties: false,
        title,
        description,
        fields,
    };
    if let Some(default) = object.get("default") {
        let default = default.as_object().ok_or_else(|| {
            unsupported_schema("malformed_default", "root default must be an object")
        })?;
        let default = Value::Object(default.clone());
        ir.validate_submission(&default).map_err(|error| {
            unsupported_schema(
                "malformed_default",
                format!("root default does not satisfy the exact payload validator: {error}"),
            )
        })?;
    }
    ir.validate_form_projection()?;
    Ok(ir)
}

fn validate_schema_serialized_size(schema: &Value) -> Result<(), GenUiError> {
    let mut writer = SchemaSizeWriter {
        bytes: 0,
        exceeded: false,
    };
    if let Err(error) = serde_json::to_writer(&mut writer, schema)
        && !writer.exceeded
    {
        return Err(unsupported_schema("malformed_schema", error.to_string()));
    }
    if writer.exceeded {
        return Err(unsupported_schema(
            "schema_too_large",
            format!("schema exceeds the {MCP_SCHEMA_MAX_BYTES} byte adapter bound"),
        ));
    }
    Ok(())
}

struct SchemaSizeWriter {
    bytes: usize,
    exceeded: bool,
}

impl Write for SchemaSizeWriter {
    fn write(&mut self, buffer: &[u8]) -> io::Result<usize> {
        let next = self.bytes.saturating_add(buffer.len());
        if next > MCP_SCHEMA_MAX_BYTES {
            self.exceeded = true;
            return Err(io::Error::new(
                io::ErrorKind::WriteZero,
                "MCP schema exceeds bounded size",
            ));
        }
        self.bytes = next;
        Ok(buffer.len())
    }

    fn flush(&mut self) -> io::Result<()> {
        Ok(())
    }
}

fn parse_schema_field(
    name: &str,
    property: &Map<String, Value>,
    required: bool,
) -> Result<McpSchemaField, GenUiError> {
    let allowed_property = [
        "type",
        "enum",
        "minimum",
        "maximum",
        "minLength",
        "maxLength",
        "pattern",
        "title",
        "description",
        "default",
        "examples",
    ];
    let type_name = property
        .get("type")
        .and_then(Value::as_str)
        .ok_or_else(|| {
            unsupported_schema("malformed_schema", format!("property {name:?} has no type"))
        })?;
    let schema_type = McpSchemaType::parse(type_name, name)?;
    reject_unknown_schema_keywords(property, &allowed_property, name)?;
    if property.contains_key("pattern") {
        return Err(unsupported_schema(
            "unsupported_keyword",
            format!("property {name:?} uses unsupported pattern"),
        ));
    }
    let allows_lengths = schema_type == McpSchemaType::String;
    if property
        .keys()
        .any(|keyword| matches!(keyword.as_str(), "minLength" | "maxLength") && !allows_lengths)
    {
        return Err(unsupported_schema(
            "wrong_type_keyword",
            format!("string length keyword on non-string property {name:?}"),
        ));
    }
    let allows_bounds = schema_type == McpSchemaType::Integer;
    if property
        .keys()
        .any(|keyword| matches!(keyword.as_str(), "minimum" | "maximum") && !allows_bounds)
    {
        return Err(unsupported_schema(
            "wrong_type_keyword",
            format!("numeric bound on non-integer property {name:?}"),
        ));
    }
    let min_length = parse_length(property, "minLength", name, allows_lengths)?;
    let max_length = parse_length(property, "maxLength", name, allows_lengths)?;
    if min_length
        .zip(max_length)
        .is_some_and(|(minimum, maximum)| minimum > maximum)
    {
        return Err(unsupported_schema(
            "malformed_bound",
            format!("property {name:?} minLength exceeds maxLength"),
        ));
    }
    let minimum = parse_integer_bound(property, "minimum", name, allows_bounds)?;
    let maximum = parse_integer_bound(property, "maximum", name, allows_bounds)?;
    if minimum
        .zip(maximum)
        .is_some_and(|(minimum, maximum)| minimum > maximum)
    {
        return Err(unsupported_schema(
            "malformed_bound",
            format!("property {name:?} minimum exceeds maximum"),
        ));
    }
    let enum_values = parse_enum(property, schema_type, name)?;
    if property.contains_key("examples") {
        return Err(unsupported_schema(
            "unsupported_annotation",
            format!("property {name:?} examples are not supported by the G3 adapter"),
        ));
    }
    let field = McpSchemaField {
        name: name.to_owned(),
        schema_type,
        required,
        enum_values,
        title: parse_metadata(property, "title", name)?,
        description: parse_metadata(property, "description", name)?,
        default: property
            .get("default")
            .map(|value| {
                McpScalarValue::parse(value, schema_type, name).map_err(|_| {
                    unsupported_schema(
                        "malformed_default",
                        format!("property {name:?} default has the wrong type"),
                    )
                })
            })
            .transpose()?,
        min_length,
        max_length,
        minimum,
        maximum,
    };
    if let Some(default) = property.get("default") {
        field.validate_default(default)?;
    }
    Ok(field)
}

fn parse_enum(
    property: &Map<String, Value>,
    schema_type: McpSchemaType,
    name: &str,
) -> Result<Vec<McpScalarValue>, GenUiError> {
    let Some(values) = property.get("enum") else {
        return Ok(Vec::new());
    };
    let values = values.as_array().ok_or_else(|| {
        unsupported_schema(
            "malformed_enum",
            format!("property {name:?} enum must be an array"),
        )
    })?;
    if values.is_empty() {
        return Err(unsupported_schema(
            "malformed_enum",
            format!("property {name:?} enum must not be empty"),
        ));
    }
    if values.len() > MCP_SCHEMA_MAX_ENUM_VALUES {
        return Err(unsupported_schema(
            "schema_too_large",
            format!("property {name:?} enum exceeds {MCP_SCHEMA_MAX_ENUM_VALUES} values"),
        ));
    }
    let mut parsed = Vec::with_capacity(values.len());
    let mut display_values = BTreeSet::new();
    for value in values {
        let scalar = McpScalarValue::parse(value, schema_type, name)?;
        if parsed.contains(&scalar) {
            return Err(unsupported_schema(
                "duplicate_enum",
                format!("property {name:?} enum contains duplicate values"),
            ));
        }
        if !display_values.insert(scalar.display()) {
            return Err(unsupported_schema(
                "ambiguous_enum",
                format!("property {name:?} enum values have the same safe display label"),
            ));
        }
        parsed.push(scalar);
    }
    Ok(parsed)
}

fn parse_length(
    property: &Map<String, Value>,
    keyword: &str,
    name: &str,
    applicable: bool,
) -> Result<Option<u64>, GenUiError> {
    let Some(value) = property.get(keyword) else {
        return Ok(None);
    };
    let length = value.as_u64().ok_or_else(|| {
        unsupported_schema(
            "malformed_bound",
            format!("property {name:?} {keyword} must be a non-negative integer"),
        )
    })?;
    if !applicable || length > MCP_SCHEMA_MAX_STRING_LENGTH {
        return Err(unsupported_schema(
            "wrong_type_keyword",
            format!("property {name:?} {keyword} is outside the exact adapter limits"),
        ));
    }
    Ok(Some(length))
}

fn parse_integer_bound(
    property: &Map<String, Value>,
    keyword: &str,
    name: &str,
    applicable: bool,
) -> Result<Option<i128>, GenUiError> {
    let Some(value) = property.get(keyword) else {
        return Ok(None);
    };
    if !applicable {
        return Err(unsupported_schema(
            "wrong_type_keyword",
            format!("numeric bound on non-integer property {name:?}"),
        ));
    }
    let number = value
        .as_i64()
        .map(i128::from)
        .or_else(|| value.as_u64().map(i128::from));
    number
        .ok_or_else(|| {
            unsupported_schema(
                "malformed_bound",
                format!("property {name:?} {keyword} must be an exact integer"),
            )
        })
        .map(Some)
}

fn parse_metadata(
    object: &Map<String, Value>,
    key: &str,
    location: &str,
) -> Result<Option<String>, GenUiError> {
    let Some(value) = object.get(key) else {
        return Ok(None);
    };
    let value = value.as_str().ok_or_else(|| {
        unsupported_schema(
            "malformed_metadata",
            format!("{key} at {location} must be a string"),
        )
    })?;
    if value.len() > DEFAULT_MAX_TEXT_BYTES {
        return Err(unsupported_schema(
            "schema_too_large",
            format!("{key} at {location} exceeds the presentation text limit"),
        ));
    }
    Ok(Some(sanitize_single_line_metadata(value)))
}

fn parse_required_fields(object: &Map<String, Value>) -> Result<BTreeSet<String>, GenUiError> {
    let Some(required) = object.get("required") else {
        return Ok(BTreeSet::new());
    };
    let values = required.as_array().ok_or_else(|| {
        unsupported_schema("malformed_required", "required must be an array of strings")
    })?;
    if values.len() > MCP_SCHEMA_MAX_FIELDS {
        return Err(unsupported_schema(
            "schema_too_large",
            format!("required count exceeds {MCP_SCHEMA_MAX_FIELDS}"),
        ));
    }
    let mut output = BTreeSet::new();
    for value in values {
        let name = value.as_str().ok_or_else(|| {
            unsupported_schema("malformed_required", "required contains a non-string entry")
        })?;
        if name.is_empty() {
            return Err(unsupported_schema(
                "malformed_required",
                "required contains an empty property name",
            ));
        }
        if !output.insert(name.to_owned()) {
            return Err(unsupported_schema(
                "duplicate_required",
                "required contains a duplicate entry",
            ));
        }
    }
    Ok(output)
}

fn reject_unknown_schema_keywords(
    object: &Map<String, Value>,
    allowed: &[&str],
    location: &str,
) -> Result<(), GenUiError> {
    if let Some(keyword) = object
        .keys()
        .find(|keyword| !allowed.contains(&keyword.as_str()))
    {
        return Err(unsupported_schema(
            "unsupported_keyword",
            format!("unsupported JSON-Schema keyword {keyword:?} at {location}"),
        ));
    }
    Ok(())
}

fn unsupported_schema(reason: &str, message: impl Into<String>) -> GenUiError {
    GenUiError::UnsupportedMcpSchema(format!("{reason}: {}", message.into()))
}

fn i128_to_json_number(value: i128) -> Option<serde_json::Number> {
    i64::try_from(value)
        .map(serde_json::Number::from)
        .ok()
        .or_else(|| u64::try_from(value).map(serde_json::Number::from).ok())
}

/// A conservative projection of canonical Agent/FalseGreen state. It shows
/// only supplied observations and never manufactures an authority verdict.
pub fn state_surface(surface_id: impl Into<String>, state: &BTreeMap<String, String>) -> Surface {
    let entries = state.clone();
    Surface::new(
        surface_id,
        Component {
            id: "state-root".to_owned(),
            kind: ComponentKind::KeyValue { entries },
        },
    )
}

#[must_use]
pub fn session_surface(session: &crate::session::Session) -> Surface {
    let mut entries = BTreeMap::new();
    entries.insert("session".to_owned(), session.id.clone());
    entries.insert("state".to_owned(), format!("{:?}", session.state));
    entries.insert("goal".to_owned(), session.goal.clone());
    entries.insert("model_turns".to_owned(), session.model_turns.to_string());
    entries.insert("tool_calls".to_owned(), session.tool_calls.to_string());
    entries.insert(
        "repair_cycles".to_owned(),
        session.repair_cycles.to_string(),
    );
    state_surface("agent-session", &entries)
}

#[must_use]
pub fn falsegreen_result_surface(result: &crate::falsegreen::FalseGreenResult) -> Surface {
    let mut entries = BTreeMap::new();
    entries.insert(
        "verification".to_owned(),
        format!("{:?}", result.verification),
    );
    entries.insert(
        "verification_status".to_owned(),
        result.verification_status.clone(),
    );
    entries.insert(
        "candidate_sha256".to_owned(),
        result.candidate_sha256.clone(),
    );
    entries.insert(
        "completion_authority".to_owned(),
        format!("{:?}", result.completion_authority),
    );
    let evidence = vec![EvidenceItem {
        label: "canonical evidence".to_owned(),
        value: sanitize_text(&result.evidence.to_string()),
    }];
    Surface::new(
        "falsegreen-verification",
        Component {
            id: "verification".to_owned(),
            kind: ComponentKind::Stack {
                children: vec![
                    Component {
                        id: "facts".to_owned(),
                        kind: ComponentKind::KeyValue { entries },
                    },
                    Component {
                        id: "evidence".to_owned(),
                        kind: ComponentKind::Evidence {
                            title: "Evidence (diagnostic projection)".to_owned(),
                            items: evidence,
                        },
                    },
                ],
            },
        },
    )
}

#[must_use]
pub fn run_outcome_surface(outcome: &crate::agent::RunOutcome) -> Surface {
    let mut entries = BTreeMap::new();
    entries.insert("session".to_owned(), outcome.session_id.clone());
    entries.insert("state".to_owned(), format!("{:?}", outcome.state));
    entries.insert("model_turns".to_owned(), outcome.model_turns.to_string());
    entries.insert("tool_calls".to_owned(), outcome.tool_calls.to_string());
    entries.insert(
        "repair_cycles".to_owned(),
        outcome.repair_cycles.to_string(),
    );
    if let Some(result) = &outcome.falsegreen_result {
        entries.insert(
            "verification".to_owned(),
            format!("{:?}", result.verification),
        );
        entries.insert(
            "candidate_sha256".to_owned(),
            result.candidate_sha256.clone(),
        );
        entries.insert(
            "completion_authority".to_owned(),
            format!("{:?}", result.completion_authority),
        );
    }
    state_surface("agent-run", &entries)
}
#[cfg(test)]
mod v3_tests {
    use super::*;
    use serde_json::json;

    fn establish_state(
        catalog: &mut ActionCatalog,
        store: &mut EventStore,
        session_id: &str,
        principal: &str,
        digest: &str,
        authorization_context: &str,
    ) {
        let generation = store
            .advance_genui_current_state(session_id, principal, digest, authorization_context)
            .expect("trusted state");
        catalog
            .set_current_state(
                session_id,
                principal,
                generation,
                digest,
                authorization_context,
            )
            .expect("catalog state");
    }

    fn bound_surface(kind: ActionKind) -> (Surface, ActionCatalog) {
        let mut surface = Surface::new("surface", Component::text("root", "ok"));
        surface.actions.push(Action {
            id: ActionCatalog::new_action_id(),
            label: "Run tool".to_owned(),
            kind,
            state_digest: "state-v1".to_owned(),
        });
        let digest = surface.digest().expect("surface digest");
        let action = &surface.actions[0];
        let mut catalog = ActionCatalog::default();
        catalog
            .bind_mcp_action_with_context(
                action,
                &surface.id,
                &digest,
                "session-1",
                "principal-1",
                "default",
                1,
                &action.state_digest,
                "provider_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                "server",
                "mcp__server__tool__aaaaaaaaaaaaaaaa",
                &"b".repeat(64),
                1,
                &sha256_hex("falsegreen.tool-policy.v1|consequential|1".as_bytes()),
                kind == ActionKind::Consequential,
                ActionSourceType::Mcp,
            )
            .expect("host binding");
        catalog
            .set_remote_tool_name(action.id.as_str(), "remote-tool")
            .expect("remote identity");
        (surface, catalog)
    }

    #[test]
    fn model_action_has_no_executable_authority_and_catalog_is_exact() {
        let (surface, mut catalog) = bound_surface(ActionKind::Consequential);
        catalog
            .set_current_state("session-1", "principal-1", 1, "state-v1", "default")
            .expect("trusted state");
        let encoded = serde_json::to_value(&surface.actions[0]).expect("serialize");
        assert!(encoded.get("binding").is_none());
        assert!(
            serde_json::from_value::<Action>(json!({
                "id": surface.actions[0].id,
                "label": "Run tool",
                "kind": "consequential",
                "state_digest": "state-v1",
                "callback": "shell"
            }))
            .is_err()
        );
        catalog
            .validate_surface(&surface, &HostCapabilities::default())
            .expect("admission");
        let mut relabeled = surface.clone();
        relabeled.actions[0].label = "Different".to_owned();
        assert!(
            catalog
                .validate_surface(&relabeled, &HostCapabilities::default())
                .is_err()
        );
        let mut rebound = surface.clone();
        rebound.actions[0].kind = ActionKind::McpTool;
        assert!(
            catalog
                .validate_surface(&rebound, &HostCapabilities::default())
                .is_err()
        );
    }

    #[test]
    fn confirmation_is_host_event_and_replay_is_durable_lifecycle() {
        let (surface, mut catalog) = bound_surface(ActionKind::Consequential);
        let action_id = surface.actions[0].id.clone();
        let payload = json!({"mode": "safe"});
        let mut store = EventStore::open_memory().expect("store");
        establish_state(
            &mut catalog,
            &mut store,
            "session-1",
            "principal-1",
            "state-v1",
            "default",
        );
        catalog
            .present_action(&mut store, "session-1", &action_id)
            .expect("present");
        let confirmation = catalog
            .request_confirmation(&mut store, "session-1", &action_id, &payload)
            .expect("request");
        catalog
            .append_confirmed_after_live_validation(&mut store, &confirmation)
            .expect("confirm");
        let identity = catalog
            .identity_for(&action_id, &payload)
            .expect("identity");
        store
            .start_genui_action("session-1", &action_id, &identity, true)
            .expect("start");
        assert!(matches!(
            store.start_genui_action("session-1", &action_id, &identity, true),
            Err(EventError::GenUiActionAlreadyStarted(_))
        ));
        let events = store.events("session-1").expect("events");
        assert!(
            events
                .iter()
                .any(|event| event.kind == EventKind::GenUiActionConfirmed)
        );
        assert!(
            events
                .iter()
                .any(|event| event.kind == EventKind::GenUiActionExecutionStarted)
        );
    }

    #[test]
    fn restart_reconciles_unknown_external_outcome_without_retry() {
        let (surface, mut catalog) = bound_surface(ActionKind::Consequential);
        let action_id = surface.actions[0].id.clone();
        let payload = json!({"mode": "safe"});
        let mut store = EventStore::open_memory().expect("store");
        establish_state(
            &mut catalog,
            &mut store,
            "session-1",
            "principal-1",
            "state-v1",
            "default",
        );
        catalog
            .present_action(&mut store, "session-1", &action_id)
            .expect("present");
        let confirmation = catalog
            .request_confirmation(&mut store, "session-1", &action_id, &payload)
            .expect("request");
        catalog
            .append_confirmed_after_live_validation(&mut store, &confirmation)
            .expect("confirm");
        let identity = catalog
            .identity_for(&action_id, &payload)
            .expect("identity");
        store
            .start_genui_action("session-1", &action_id, &identity, true)
            .expect("start");
        assert_eq!(
            store
                .reconcile_genui_actions("session-1")
                .expect("reconcile"),
            1
        );
        assert!(matches!(
            store.start_genui_action("session-1", &action_id, &identity, true),
            Err(EventError::GenUiActionOutcomeUnknown(_))
        ));
    }

    #[test]
    fn persisted_lifecycle_handles_crash_windows_without_replay() {
        let (surface, mut catalog) = bound_surface(ActionKind::Consequential);
        let action_id = surface.actions[0].id.clone();
        let payload = json!({"mode": "safe"});
        let directory = tempfile::tempdir().expect("temporary event store");
        let path = directory.path().join("events.db");

        // Crash A: confirmation is durable, but execution has not started;
        // reopening permits the action to proceed.
        {
            let mut store = EventStore::open(&path).expect("open");
            establish_state(
                &mut catalog,
                &mut store,
                "session-1",
                "principal-1",
                "state-v1",
                "default",
            );
            catalog
                .present_action(&mut store, "session-1", &action_id)
                .expect("present");
            let confirmation = catalog
                .request_confirmation(&mut store, "session-1", &action_id, &payload)
                .expect("request");
            catalog
                .append_confirmed_after_live_validation(&mut store, &confirmation)
                .expect("confirm");
        }
        let mut store = EventStore::open(&path).expect("reopen");
        let identity = catalog
            .identity_for(&action_id, &payload)
            .expect("identity");
        store
            .start_genui_action("session-1", &action_id, &identity, true)
            .expect("retry after pre-start crash");
        drop(store);

        // Crash B: a committed start with no durable external result becomes
        // unknown and is never blindly retried.
        let mut store = EventStore::open(&path).expect("reopen after start");
        assert_eq!(
            store
                .reconcile_genui_actions("session-1")
                .expect("reconcile"),
            1
        );
        assert!(matches!(
            store.start_genui_action("session-1", &action_id, &identity, true),
            Err(EventError::GenUiActionOutcomeUnknown(_))
        ));

        // Crash C: once completion is durable, activation remains single-use
        // even after reopening the existing Agent database.
        let completed_path = directory.path().join("completed.db");
        {
            let mut completed = EventStore::open(&completed_path).expect("completed store");
            establish_state(
                &mut catalog,
                &mut completed,
                "session-1",
                "principal-1",
                "state-v1",
                "default",
            );
            catalog
                .present_action(&mut completed, "session-1", &action_id)
                .expect("present");
            let confirmation = catalog
                .request_confirmation(&mut completed, "session-1", &action_id, &payload)
                .expect("request");
            catalog
                .append_confirmed_after_live_validation(&mut completed, &confirmation)
                .expect("confirm");
            completed
                .start_genui_action("session-1", &action_id, &identity, true)
                .expect("start");
            completed
                .complete_genui_action("session-1", &action_id, &identity, true, &"c".repeat(64))
                .expect("complete");
        }
        let mut completed = EventStore::open(&completed_path).expect("reopen completed store");
        assert!(matches!(
            completed.start_genui_action("session-1", &action_id, &identity, true),
            Err(EventError::GenUiActionAlreadyStarted(_))
        ));
    }

    #[test]
    fn schema_subset_fails_closed_for_unsupported_constructs() {
        for schema in [
            json!({"type":"object","properties":{},"additionalProperties":true}),
            json!({"type":"object","properties":{}}),
        ] {
            assert!(matches!(
                validate_mcp_submission(&schema, &json!({})),
                Err(GenUiError::UnsupportedMcpSchema(_))
            ));
        }
        let exact = json!({
            "type":"object",
            "properties":{"x":{"type":"string"}},
            "additionalProperties":false
        });
        assert!(validate_mcp_submission(&exact, &json!({"x":"ok"})).is_ok());
        assert!(matches!(
            validate_mcp_submission(&exact, &json!({"x":"ok","extra":true})),
            Err(GenUiError::InvalidMcpSubmission(_))
        ));
        let patterned =
            json!({"type":"object","properties":{"x":{"type":"string","pattern":"^[A-Z]+$"}}});
        assert!(matches!(
            validate_mcp_submission(&patterned, &json!({"x":"OK"})),
            Err(GenUiError::UnsupportedMcpSchema(_))
        ));
        let schema_valued = json!({"type":"object","properties":{"x":{"type":"string"}},"additionalProperties":{"type":"string"}});
        assert!(matches!(
            validate_mcp_submission(&schema_valued, &json!({"x":"ok","y":"ok"})),
            Err(GenUiError::UnsupportedMcpSchema(_))
        ));
        let integer = json!({"type":"object","properties":{"x":{"type":"integer"}},"additionalProperties":false});
        assert!(validate_mcp_submission(&integer, &json!({"x":1})).is_ok());
        assert!(validate_mcp_submission(&integer, &json!({"x":1.0})).is_err());
        let duplicate_enum =
            json!({"type":"object","properties":{"x":{"type":"string","enum":["a","a"]}}});
        assert!(matches!(
            mcp_tool_surface(
                "surface",
                "mcp__server__tool__aaaaaaaaaaaaaaaa",
                &duplicate_enum,
                "state"
            ),
            Err(GenUiError::UnsupportedMcpSchema(_))
        ));
    }

    #[test]
    fn labels_reject_terminal_spoofing_and_width_is_display_cell_based() {
        let mut surface = Surface::new("surface", Component::text("root", "界e\u{301}"));
        surface.actions.push(Action {
            id: ActionCatalog::new_action_id(),
            label: "bad\u{202e}label".to_owned(),
            kind: ActionKind::McpTool,
            state_digest: "state".to_owned(),
        });
        assert!(surface.validate().is_err());
        let negotiated = default_negotiated_capabilities(4);
        let safe = Surface::new("safe", Component::text("root", "界e\u{301}"));
        let rendered = render_surface_with_capabilities(&safe, &negotiated).expect("render");
        use unicode_width::UnicodeWidthStr;
        assert!(rendered.lines().all(|line| line.width() <= 4));
    }

    #[test]
    fn negotiated_component_policy_and_shape_bounds_remain_intact() {
        let surface = Surface::new("surface", Component::text("root", "ok"));
        let mut host = HostCapabilities::default();
        host.supported_components.remove("text");
        host.unsupported_component_policy = UnsupportedComponentPolicy::Reject;
        assert!(matches!(
            surface.validate_with(&host),
            Err(GenUiError::UnsupportedComponent { .. })
        ));
        host.unsupported_component_policy = UnsupportedComponentPolicy::Placeholder;
        surface.validate_with(&host).expect("placeholder policy");
        let oversized = Surface::new(
            "large",
            Component::text("root", "x".repeat(DEFAULT_MAX_TEXT_BYTES + 1)),
        );
        assert!(oversized.validate().is_err());
    }

    #[test]
    fn terminal_control_sequences_are_inert_in_general_text() {
        let value = sanitize_text(
            "\u{1b}[31mred\u{1b}[0m \u{1b}]8;;https://evil.example\u{7}link\u{1b}]8;;\u{7} \u{1b}Psecret\u{1b}\\tail",
        );
        assert_eq!(value, "red link tail");
        assert!(!value.contains('\u{1b}'));
    }

    #[test]
    fn protocol_negotiation_rejects_unknown_major_versions() {
        let host = HostCapabilities::default();
        assert!(matches!(
            negotiate(&[ProtocolVersion { major: 2, minor: 0 }], &host),
            Err(GenUiError::UnsupportedProtocol { .. })
        ));
    }
}

#[cfg(test)]
mod v4_tests {
    use super::*;
    use serde_json::json;

    fn bound() -> (Surface, ActionCatalog) {
        let mut surface = Surface::new("v4-surface", Component::text("root", "ok"));
        surface.actions.push(Action {
            id: ActionCatalog::new_action_id(),
            label: "Run".to_owned(),
            kind: ActionKind::Consequential,
            state_digest: "state-v4".to_owned(),
        });
        let digest = surface.digest().expect("surface digest");
        let action = &surface.actions[0];
        let mut catalog = ActionCatalog::default();
        catalog
            .bind_mcp_action_with_context(
                action,
                &surface.id,
                &digest,
                "session-v4",
                "principal-v4",
                "default",
                1,
                &action.state_digest,
                "provider_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                "server-v4",
                "mcp__server__tool__aaaaaaaaaaaaaaaa",
                &"a".repeat(64),
                1,
                &sha256_hex("falsegreen.tool-policy.v1|consequential|1".as_bytes()),
                true,
                ActionSourceType::Mcp,
            )
            .expect("bind");
        catalog
            .set_remote_tool_name(action.id.as_str(), "remote-tool")
            .expect("remote identity");
        (surface, catalog)
    }

    #[test]
    fn lifecycle_rejects_out_of_order_and_terminal_resurrection() {
        let (surface, mut catalog) = bound();
        let id = &surface.actions[0].id;
        let payload = json!({"x": "y"});
        let identity = catalog.identity_for(id, &payload).expect("identity");
        let mut store = EventStore::open_memory().expect("store");
        let generation = store
            .advance_genui_current_state("session-v4", "principal-v4", "state-v4", "default")
            .expect("trusted state");
        catalog
            .set_current_state(
                "session-v4",
                "principal-v4",
                generation,
                "state-v4",
                "default",
            )
            .expect("catalog state");
        assert!(
            store
                .append("session-v4", EventKind::GenUiActionConfirmed, &identity)
                .is_err()
        );
        catalog
            .present_action(&mut store, "session-v4", id)
            .expect("present");
        let confirmation = catalog
            .request_confirmation(&mut store, "session-v4", id, &payload)
            .expect("request");
        catalog
            .append_confirmed_after_live_validation(&mut store, &confirmation)
            .expect("confirm");
        store
            .start_genui_action("session-v4", id, &identity, true)
            .expect("start");
        store
            .complete_genui_action("session-v4", id, &identity, true, &"d".repeat(64))
            .expect("terminal");
        assert!(
            catalog
                .request_confirmation(&mut store, "session-v4", id, &payload)
                .is_err()
        );
        assert!(
            store
                .start_genui_action("session-v4", id, &identity, true)
                .is_err()
        );
    }

    #[test]
    fn generic_event_append_cannot_write_genui_namespace() {
        let (_, catalog) = bound();
        let identity = catalog
            .identity_for(catalog.bindings.keys().next().expect("action"), &json!({}))
            .expect("identity");
        let mut store = EventStore::open_memory().expect("store");
        assert!(matches!(
            store.append("session-v4", EventKind::GenUiActionPresented, &identity),
            Err(EventError::GenUiEventMustUseLifecycle)
        ));
    }

    #[test]
    fn host_state_and_renderer_admission_stale_actions() {
        let (surface, mut catalog) = bound();
        catalog
            .set_current_state("session-v4", "principal-v4", 2, "state-v5", "default")
            .expect("state update");
        assert!(
            catalog
                .validate_surface(&surface, &HostCapabilities::default())
                .is_err()
        );

        let mut safe_surface = surface.clone();
        safe_surface.actions[0].state_digest = "state-v5".to_owned();
        let digest = safe_surface.digest().expect("digest");
        catalog.remove(&safe_surface.actions[0].id);
        catalog
            .bind_mcp_action_with_context(
                &safe_surface.actions[0],
                &safe_surface.id,
                &digest,
                "session-v4",
                "principal-v4",
                "default",
                2,
                "state-v5",
                "provider_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                "server-v4",
                "mcp__server__tool__aaaaaaaaaaaaaaaa",
                &"a".repeat(64),
                1,
                &sha256_hex("falsegreen.tool-policy.v1|consequential|1".as_bytes()),
                true,
                ActionSourceType::Mcp,
            )
            .expect("rebind");
        let mut caps = default_negotiated_capabilities(80);
        caps.supported_components.remove("text");
        let rendered =
            render_surface_with_capabilities_and_catalog(&safe_surface, &caps, &mut catalog)
                .expect("placeholder render");
        assert!(rendered.contains("unsupported component"));
        assert!(!rendered.contains("gui_action_"));
        assert!(catalog.resolve(&safe_surface.actions[0].id).is_none());
    }

    #[test]
    fn catalog_mutations_are_transactional_and_bump_once() {
        let mut store = EventStore::open_memory().expect("store");
        let generation = store
            .advance_genui_current_state("tx-session", "tx-principal", "state", "auth")
            .expect("durable state");
        let action = Action {
            id: ActionCatalog::new_action_id(),
            label: "Read".to_owned(),
            kind: ActionKind::McpTool,
            state_digest: "state".to_owned(),
        };
        let surface = Surface::new("tx-surface", Component::text("root", "ok"));
        let surface_digest = surface.digest().expect("surface digest");
        let schema_digest = "a".repeat(64);
        let mut catalog = ActionCatalog::default();
        let initial_generation = catalog.generation();
        catalog
            .bind_mcp_action_with_remote(
                &store,
                &action,
                &surface.id,
                &surface_digest,
                "tx-session",
                "tx-principal",
                "provider",
                "server",
                "exposed",
                "remote",
                &schema_digest,
                false,
            )
            .expect("successful transactional bind");
        assert_eq!(catalog.generation(), initial_generation + 1);
        let committed_digest = catalog.digest();
        assert!(catalog.resolve(&action.id).is_some());
        catalog
            .bind_action_owner(&action.id, "owner-one")
            .expect("first owner");
        let owner_generation = catalog.generation();
        let owner_digest = catalog.digest();
        assert!(catalog.bind_action_owner(&action.id, "owner-two").is_err());
        assert_eq!(catalog.generation(), owner_generation);
        assert_eq!(catalog.digest(), owner_digest);

        let before_failed_bind = catalog.digest();
        let before_failed_generation = catalog.generation();
        assert!(
            catalog
                .bind_mcp_action_with_remote(
                    &store,
                    &action,
                    &surface.id,
                    &surface_digest,
                    "tx-session",
                    "tx-principal",
                    "provider",
                    "server",
                    "exposed",
                    "",
                    &schema_digest,
                    false,
                )
                .is_err()
        );
        assert_eq!(catalog.generation(), before_failed_generation);
        assert_eq!(catalog.digest(), before_failed_bind);

        let stale = Action {
            id: ActionCatalog::new_action_id(),
            label: "Stale".to_owned(),
            kind: ActionKind::McpTool,
            state_digest: "stale-state".to_owned(),
        };
        let stale_digest = catalog.digest();
        let stale_generation = catalog.generation();
        assert!(
            catalog
                .bind_mcp_action_with_remote(
                    &store,
                    &stale,
                    &surface.id,
                    &surface_digest,
                    "tx-session",
                    "tx-principal",
                    "provider",
                    "server",
                    "exposed",
                    "remote",
                    &schema_digest,
                    false,
                )
                .is_err()
        );
        assert_eq!(catalog.generation(), stale_generation);
        assert_eq!(catalog.digest(), stale_digest);
        assert!(catalog.resolve(&stale.id).is_none());

        let invalid = Action {
            id: ActionCatalog::new_action_id(),
            label: "Local".to_owned(),
            kind: ActionKind::Navigation,
            state_digest: "state".to_owned(),
        };
        let invalid_digest = catalog.digest();
        let invalid_generation = catalog.generation();
        assert!(
            catalog
                .bind_mcp_action_with_context(
                    &invalid,
                    &surface.id,
                    &surface_digest,
                    "tx-session",
                    "tx-principal",
                    "auth",
                    generation,
                    "state",
                    "provider",
                    "server",
                    "exposed",
                    &schema_digest,
                    1,
                    &"b".repeat(64),
                    false,
                    ActionSourceType::Mcp,
                )
                .is_err()
        );
        assert_eq!(catalog.generation(), invalid_generation);
        assert_eq!(catalog.digest(), invalid_digest);
        assert_ne!(committed_digest, owner_digest);
    }

    #[test]
    fn public_binding_requires_existing_durable_state_and_cannot_seed_authority() {
        let mut surface = Surface::new("safe-bind", Component::text("root", "ok"));
        surface.actions.push(Action {
            id: ActionCatalog::new_action_id(),
            label: "Run".to_owned(),
            kind: ActionKind::Consequential,
            state_digest: "attacker".to_owned(),
        });
        let digest = surface.digest().expect("surface digest");
        let mut catalog = ActionCatalog::default();
        let store = EventStore::open_memory().expect("store");
        let result = catalog.bind_mcp_action_with_remote(
            &store,
            &surface.actions[0],
            &surface.id,
            &digest,
            "safe-session",
            "safe-principal",
            "provider_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
            "server",
            "mcp__server__tool__aaaaaaaaaaaaaaaa",
            "remote-tool",
            &"b".repeat(64),
            true,
        );
        assert!(result.is_err());
        assert!(catalog.resolve(&surface.actions[0].id).is_none());
        assert!(
            store
                .genui_current_state("safe-session", "safe-principal")
                .expect("state query")
                .is_none()
        );
    }

    #[test]
    fn store_renderer_fails_closed_for_deleted_or_advanced_state() {
        let (surface, mut catalog) = bound();
        let directory = tempfile::tempdir().expect("store directory");
        let path = directory.path().join("events.db");
        let mut store = EventStore::open(&path).expect("store");
        let generation = store
            .advance_genui_current_state("session-v4", "principal-v4", "state-v4", "default")
            .expect("state");
        catalog
            .set_current_state(
                "session-v4",
                "principal-v4",
                generation,
                "state-v4",
                "default",
            )
            .expect("catalog state");
        let capabilities = default_negotiated_capabilities(80);
        let rendered = render_surface_with_capabilities_and_catalog_with_store(
            &surface,
            &capabilities,
            &mut catalog,
            &store,
        )
        .expect("valid render");
        assert!(rendered.contains(&surface.actions[0].id));

        store
            .advance_genui_current_state("session-v4", "principal-v4", "state-v5", "default")
            .expect("state advance");
        let mut advanced_catalog = catalog.clone();
        let rendered = render_surface_with_capabilities_and_catalog_with_store(
            &surface,
            &capabilities,
            &mut advanced_catalog,
            &store,
        )
        .expect("stale state is a valid presentation");
        assert!(!rendered.contains(&surface.actions[0].id));
        assert!(advanced_catalog.resolve(&surface.actions[0].id).is_none());

        let path = store.path().expect("path").to_owned();
        drop(store);
        rusqlite::Connection::open(&path)
            .expect("raw connection")
            .execute(
                "DELETE FROM genui_current_states WHERE session_id = ?1 AND principal = ?2",
                rusqlite::params!["session-v4", "principal-v4"],
            )
            .expect("delete state");
        let store = EventStore::open(&path).expect("reopen");
        let rendered = render_surface_with_capabilities_and_catalog_with_store(
            &surface,
            &capabilities,
            &mut catalog,
            &store,
        )
        .expect("missing state is a valid presentation");
        assert!(!rendered.contains(&surface.actions[0].id));
        assert!(catalog.resolve(&surface.actions[0].id).is_none());
    }

    #[test]
    fn store_renderer_preserves_valid_sibling_when_other_state_is_missing() {
        let mut surface = Surface::new(
            "mixed-store",
            Component {
                id: "root".to_owned(),
                kind: ComponentKind::Stack {
                    children: vec![
                        Component::text("valid", "valid"),
                        Component::text("stale", "stale"),
                    ],
                },
            },
        );
        surface.actions = vec![
            Action {
                id: "gui_action_store_valid".to_owned(),
                label: "Valid".to_owned(),
                kind: ActionKind::McpTool,
                state_digest: "state-v4".to_owned(),
            },
            Action {
                id: "gui_action_store_stale".to_owned(),
                label: "Stale".to_owned(),
                kind: ActionKind::McpTool,
                state_digest: "state-v4".to_owned(),
            },
        ];
        let digest = surface.digest().expect("surface digest");
        let policy = sha256_hex("falsegreen.tool-policy.v1|read_only|1".as_bytes());
        let mut catalog = ActionCatalog::default();
        for (action, session_id, principal) in [
            (
                &surface.actions[0],
                "mixed-valid-session",
                "mixed-valid-principal",
            ),
            (
                &surface.actions[1],
                "mixed-stale-session",
                "mixed-stale-principal",
            ),
        ] {
            catalog
                .bind_mcp_action_with_context(
                    action,
                    &surface.id,
                    &digest,
                    session_id,
                    principal,
                    "default",
                    1,
                    "state-v4",
                    "provider_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                    "server",
                    "mcp__server__tool__aaaaaaaaaaaaaaaa",
                    &"a".repeat(64),
                    1,
                    &policy,
                    false,
                    ActionSourceType::Mcp,
                )
                .expect("binding");
        }
        let directory = tempfile::tempdir().expect("store directory");
        let path = directory.path().join("events.db");
        let mut store = EventStore::open(&path).expect("store");
        let generation = store
            .advance_genui_current_state(
                "mixed-valid-session",
                "mixed-valid-principal",
                "state-v4",
                "default",
            )
            .expect("valid durable state");
        catalog
            .set_current_state(
                "mixed-valid-session",
                "mixed-valid-principal",
                generation,
                "state-v4",
                "default",
            )
            .expect("valid catalog state");
        let rendered = render_surface_with_capabilities_and_catalog_with_store(
            &surface,
            &default_negotiated_capabilities(80),
            &mut catalog,
            &store,
        )
        .expect("mixed render");
        assert!(rendered.contains("gui_action_store_valid"));
        assert!(!rendered.contains("gui_action_store_stale"));
        assert!(catalog.resolve("gui_action_store_valid").is_some());
        assert!(catalog.resolve("gui_action_store_stale").is_none());
    }

    #[test]
    fn store_renderer_validates_exact_incoming_action_and_preserves_valid_siblings() {
        let mut surface = Surface::new(
            "exact-render",
            Component {
                id: "root".to_owned(),
                kind: ComponentKind::Stack {
                    children: vec![Component::text("one", "one"), Component::text("two", "two")],
                },
            },
        );
        surface.actions = vec![
            Action {
                id: "gui_action_exact_one".to_owned(),
                label: "One".to_owned(),
                kind: ActionKind::McpTool,
                state_digest: "state-exact".to_owned(),
            },
            Action {
                id: "gui_action_exact_two".to_owned(),
                label: "Two".to_owned(),
                kind: ActionKind::McpTool,
                state_digest: "state-exact".to_owned(),
            },
        ];
        let digest = surface.digest().expect("structural digest");
        let policy = sha256_hex("falsegreen.tool-policy.v1|read_only|1".as_bytes());
        let mut catalog = ActionCatalog::default();
        for action in &surface.actions {
            catalog
                .bind_mcp_action_with_context(
                    action,
                    &surface.id,
                    &digest,
                    "exact-session",
                    "exact-principal",
                    "default",
                    1,
                    "state-exact",
                    "provider_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                    "server",
                    "mcp__server__tool__aaaaaaaaaaaaaaaa",
                    &"a".repeat(64),
                    1,
                    &policy,
                    false,
                    ActionSourceType::Mcp,
                )
                .expect("binding");
            catalog
                .set_remote_tool_name(&action.id, "remote-tool")
                .expect("remote identity");
        }
        let mut store = EventStore::open_memory().expect("store");
        let generation = store
            .advance_genui_current_state(
                "exact-session",
                "exact-principal",
                "state-exact",
                "default",
            )
            .expect("state");
        catalog
            .set_current_state(
                "exact-session",
                "exact-principal",
                generation,
                "state-exact",
                "default",
            )
            .expect("catalog state");
        let caps = default_negotiated_capabilities(80);
        let valid = render_surface_with_capabilities_and_catalog_with_store(
            &surface,
            &caps,
            &mut catalog.clone(),
            &store,
        )
        .expect("valid render");
        assert!(valid.contains("gui_action_exact_one"));
        assert!(valid.contains("gui_action_exact_two"));

        let mut mutated = surface.clone();
        mutated.actions[0].label = "Totally Safe".to_owned();
        let mut mutated_catalog = catalog.clone();
        let rendered = render_surface_with_capabilities_and_catalog_with_store(
            &mutated,
            &caps,
            &mut mutated_catalog,
            &store,
        )
        .expect("mutated render");
        assert!(!rendered.contains("gui_action_exact_one"));
        assert!(rendered.contains("gui_action_exact_two"));

        let mut revoked_catalog = catalog;
        revoked_catalog.remove("gui_action_exact_one");
        let rendered = render_surface_with_capabilities_and_catalog_with_store(
            &surface,
            &caps,
            &mut revoked_catalog,
            &store,
        )
        .expect("revoked render");
        assert!(!rendered.contains("gui_action_exact_one"));
    }

    #[test]
    fn dialect_and_numeric_subset_are_exact() {
        for dialect in [
            "urn:attacker-draft-07-marker",
            "draft-07-but-not-really",
            "https://json-schema.org/draft/2019-09/schema",
        ] {
            assert!(
                validate_mcp_submission(&json!({"$schema": dialect, "type": "object"}), &json!({}))
                    .is_err()
            );
        }
        assert!(validate_mcp_submission(
            &json!({"$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "additionalProperties": false}),
            &json!({})
        )
        .is_ok());
        assert!(
            validate_mcp_submission(
                &json!({"type": "object", "properties": {"x": {"type": "number"}}}),
                &json!({"x": 1.2})
            )
            .is_err()
        );
    }

    #[test]
    fn schema_keyword_applicability_fails_closed() {
        for schema in [
            json!({"type":"object", "properties":{"x":{"type":"string","minimum":1}}}),
            json!({"type":"object", "properties":{"x":{"type":"boolean","minimum":1}}}),
            json!({"type":"object", "properties":{"x":{"type":"integer","minLength":1}}}),
            json!({"type":"object", "properties":{"x":{"type":"boolean","minLength":1}}}),
            json!({"type":"object", "properties":{"x":{"type":"integer","enum":[true]}}}),
        ] {
            assert!(validate_mcp_submission(&schema, &json!({})).is_err());
        }
        let valid = json!({
            "$schema":"https://json-schema.org/draft/2020-12/schema",
            "type":"object",
            "properties":{
                "name":{"type":"string","minLength":1},
                "count":{"type":"integer","minimum":0},
                "enabled":{"type":"boolean"}
            },
            "additionalProperties":false
        });
        assert!(
            validate_mcp_submission(&valid, &json!({"name":"ok","count":1,"enabled":true})).is_ok()
        );
    }

    #[test]
    fn schema_bounds_are_iterative_and_reject_deep_annotations_before_digest() {
        let mut just_below = json!("leaf");
        for _ in 0..(MCP_SCHEMA_MAX_JSON_DEPTH - 1) {
            just_below = Value::Array(vec![just_below]);
        }
        assert!(validate_schema_json_bounds(&just_below).is_ok());

        let mut at_limit = json!("leaf");
        for _ in 0..MCP_SCHEMA_MAX_JSON_DEPTH {
            at_limit = Value::Array(vec![at_limit]);
        }
        assert!(validate_schema_json_bounds(&at_limit).is_ok());

        let mut over_limit = json!("leaf");
        for _ in 0..=MCP_SCHEMA_MAX_JSON_DEPTH {
            over_limit = Value::Array(vec![over_limit]);
        }
        let error = validate_schema_json_bounds(&over_limit).expect_err("depth limit");
        assert!(error.to_string().contains("schema_depth_exceeded"));

        for nesting in [100usize, 1_000, 5_000] {
            let mut annotation = json!("attacker");
            for _ in 0..nesting {
                annotation = Value::Array(vec![annotation]);
            }
            let mut schema_object = Map::new();
            schema_object.insert("type".to_owned(), Value::String("object".to_owned()));
            schema_object.insert("additionalProperties".to_owned(), Value::Bool(false));
            schema_object.insert("examples".to_owned(), annotation);
            let schema = Value::Object(schema_object);
            let error = adapt_mcp_schema(&schema).expect_err("deep annotation must fail closed");
            assert!(
                error.to_string().contains("schema_depth_exceeded"),
                "nesting {nesting}: {error}"
            );
            // The public digest path is independently stack-safe for the same
            // hostile value, even though adaptation rejects it.
            assert_eq!(mcp_schema_digest(&schema).len(), 64);
            // serde_json::Value itself has a recursive destructor for deeply
            // nested arrays. Leak this synthetic attacker value after the
            // adapter returns so the probe measures adapter safety rather than
            // an unrelated caller-side destructor limitation.
            std::mem::forget(schema);
        }
    }

    #[test]
    fn examples_and_id_are_explicitly_unsupported() {
        let examples = json!({
            "type": "object",
            "additionalProperties": false,
            "examples": [{"x": "nested"}]
        });
        let error = adapt_mcp_schema(&examples).expect_err("examples policy");
        assert!(error.to_string().contains("unsupported_annotation"));

        let property_examples = json!({
            "type": "object",
            "additionalProperties": false,
            "properties": {"x": {"type": "string", "examples": ["ok"]}}
        });
        let error = adapt_mcp_schema(&property_examples).expect_err("property examples policy");
        assert!(error.to_string().contains("unsupported_annotation"));

        for identifier in ["not a URI", "\u{1b}[31murn:attacker", "urn:ok"] {
            let schema = json!({
                "type": "object",
                "additionalProperties": false,
                "$id": identifier
            });
            let error = adapt_mcp_schema(&schema).expect_err("$id policy");
            assert!(error.to_string().contains("unsupported_keyword"));
        }
    }

    #[test]
    fn root_default_uses_exact_payload_validation() {
        let base = json!({
            "type": "object",
            "properties": {
                "x": {"type": "integer", "minimum": 1, "maximum": 3},
                "mode": {"type": "string", "enum": ["safe", "fast"]}
            },
            "required": ["x"],
            "additionalProperties": false
        });
        for default in [
            json!({}),
            json!({"x": 1, "extra": true}),
            json!({"x": "1"}),
            json!({"x": 9}),
            json!({"x": 1, "mode": "unsafe"}),
        ] {
            let mut schema = base.clone();
            schema["default"] = default;
            let error = adapt_mcp_schema(&schema).expect_err("invalid root default");
            assert!(error.to_string().contains("malformed_default"));
        }

        let mut valid = base;
        valid["default"] = json!({"x": 2});
        assert!(adapt_mcp_schema(&valid).is_ok());
    }

    #[test]
    fn metadata_is_single_line_and_support_matches_surface_limits() {
        let fake = "line1\n[gui_action_fake] line2\r\n\t\u{202e}\u{200b}";
        let safe = sanitize_single_line_metadata(fake);
        assert_eq!(safe, "line1 [gui_action_fake] line2");
        assert!(!safe.contains('\n'));
        assert!(!safe.contains('\r'));
        assert!(!safe.contains('\t'));

        let mut supported_properties = Map::new();
        let mut enum_values = Vec::new();
        for index in 0..MCP_SCHEMA_MAX_ENUM_VALUES {
            enum_values.push(json!(format!("choice-{index}")));
        }
        supported_properties.insert(
            "choice".to_owned(),
            json!({"type": "string", "enum": enum_values}),
        );
        let supported = json!({
            "type": "object",
            "properties": supported_properties,
            "additionalProperties": false
        });
        let ir = adapt_mcp_schema(&supported).expect("just-under enum limit supported");
        assert_eq!(ir.fields[0].enum_values.len(), MCP_SCHEMA_MAX_ENUM_VALUES);
        assert!(
            mcp_tool_surface(
                "supported",
                "mcp__fixture__tool__aaaaaaaaaaaaaaaa",
                &supported,
                "state"
            )
            .is_ok()
        );

        let mut over_values = Vec::new();
        for index in 0..=MCP_SCHEMA_MAX_ENUM_VALUES {
            over_values.push(json!(format!("choice-{index}")));
        }
        let refused = json!({
            "type": "object",
            "properties": {"choice": {"type": "string", "enum": over_values}},
            "additionalProperties": false
        });
        let error = adapt_mcp_schema(&refused).expect_err("over enum limit refused");
        assert!(error.to_string().contains("schema_too_large"));
        assert!(
            mcp_tool_surface(
                "refused",
                "mcp__fixture__tool__aaaaaaaaaaaaaaaa",
                &refused,
                "state"
            )
            .is_err()
        );

        let collision = json!({
            "type": "object",
            "properties": {"choice": {"type": "string", "enum": ["a\nb", "a b"]}},
            "additionalProperties": false
        });
        let error = adapt_mcp_schema(&collision).expect_err("sanitized enum collision");
        assert!(error.to_string().contains("ambiguous_enum"));
    }

    #[test]
    fn renderer_revokes_only_unsupported_subtree_actions() {
        let mut surface = Surface::new(
            "mixed",
            Component {
                id: "root".to_owned(),
                kind: ComponentKind::Stack {
                    children: vec![
                        Component::text("supported", "supported"),
                        Component {
                            id: "unsupported".to_owned(),
                            kind: ComponentKind::Markdown {
                                markdown: "degraded".to_owned(),
                            },
                        },
                    ],
                },
            },
        );
        surface.actions = vec![
            Action {
                id: "gui_action_supported".to_owned(),
                label: "Supported".to_owned(),
                kind: ActionKind::Consequential,
                state_digest: "state".to_owned(),
            },
            Action {
                id: "gui_action_unsupported".to_owned(),
                label: "Unsupported".to_owned(),
                kind: ActionKind::Consequential,
                state_digest: "state".to_owned(),
            },
        ];
        let digest = surface.digest().expect("surface digest");
        let mut catalog = ActionCatalog::default();
        for action in &surface.actions {
            catalog
                .bind_mcp_action_with_context(
                    action,
                    &surface.id,
                    &digest,
                    "session-mixed",
                    "principal-mixed",
                    "default",
                    1,
                    &action.state_digest,
                    "provider_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                    "server-mixed",
                    "mcp__server__tool__aaaaaaaaaaaaaaaa",
                    &"a".repeat(64),
                    1,
                    &sha256_hex("falsegreen.tool-policy.v1|consequential|1".as_bytes()),
                    true,
                    ActionSourceType::Mcp,
                )
                .expect("bind");
            catalog
                .set_remote_tool_name(action.id.as_str(), "remote-tool")
                .expect("remote identity");
        }
        catalog
            .set_current_state("session-mixed", "principal-mixed", 1, "state", "default")
            .expect("trusted state");
        catalog
            .bind_action_owner("gui_action_supported", "supported")
            .expect("supported owner");
        catalog
            .bind_action_owner("gui_action_unsupported", "unsupported")
            .expect("unsupported owner");
        let mut capabilities = default_negotiated_capabilities(80);
        capabilities.supported_components.remove("markdown");
        let rendered =
            render_surface_with_capabilities_and_catalog(&surface, &capabilities, &mut catalog)
                .expect("placeholder render");
        assert!(rendered.contains("gui_action_supported"));
        assert!(!rendered.contains("gui_action_unsupported"));
        assert!(catalog.resolve("gui_action_supported").is_some());
        assert!(catalog.resolve("gui_action_unsupported").is_none());
    }

    #[test]
    fn schema_ir_preserves_typed_values_and_reconstructs_without_coercion() {
        let schema = json!({
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "title": "Input\u{1b}[31m",
            "description": "description\u{202e}marker",
            "properties": {
                "mode": {
                    "type": "string",
                    "enum": ["safe", "fast"],
                    "default": "safe",
                    "title": "Mode\u{200b}",
                    "description": "Choose a mode"
                },
                "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 9,
                    "enum": [1, 3, 9],
                    "default": 3
                },
                "enabled": {
                    "type": "boolean",
                    "enum": [true, false]
                },
                "note": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 20
                }
            },
            "required": ["mode", "count", "enabled"],
            "additionalProperties": false
        });
        let ir = adapt_mcp_schema(&schema).expect("exact schema IR");
        assert_eq!(ir.adapter, MCP_SCHEMA_ADAPTER_ID);
        assert_eq!(
            ir.dialect_uri(),
            Some("https://json-schema.org/draft/2020-12/schema")
        );
        assert_eq!(ir.source_digest(), mcp_schema_digest(&schema));
        assert_eq!(ir.title.as_deref(), Some("Input"));
        assert_eq!(ir.description.as_deref(), Some("description marker"));
        assert_eq!(ir.fields.len(), 4);
        let form = ir.form_fields();
        let count = ir
            .fields
            .iter()
            .find(|field| field.name == "count")
            .unwrap();
        assert_eq!(
            count.enum_values,
            vec![
                McpScalarValue::Integer(1),
                McpScalarValue::Integer(3),
                McpScalarValue::Integer(9)
            ]
        );
        let count_form = form.iter().find(|field| field.id == "count").unwrap();
        assert_eq!(count_form.choice_values, vec![json!(1), json!(3), json!(9)]);
        let enabled_form = form.iter().find(|field| field.id == "enabled").unwrap();
        assert_eq!(enabled_form.choice_values, vec![json!(true), json!(false)]);
        let mode_form = form.iter().find(|field| field.id == "mode").unwrap();
        assert_eq!(mode_form.label, "Mode");
        assert_eq!(mode_form.description.as_deref(), Some("Choose a mode"));

        let values = BTreeMap::from([
            ("mode".to_owned(), json!("fast")),
            ("count".to_owned(), json!(9)),
            ("enabled".to_owned(), json!(true)),
        ]);
        let payload = reconstruct_mcp_payload(&schema, &values).expect("payload");
        assert_eq!(
            payload,
            json!({"mode": "fast", "count": 9, "enabled": true})
        );
        assert!(
            reconstruct_mcp_payload(
                &schema,
                &BTreeMap::from([
                    ("mode".to_owned(), json!("fast")),
                    ("count".to_owned(), json!("9")),
                    ("enabled".to_owned(), json!(true)),
                ])
            )
            .is_err()
        );
        assert!(
            reconstruct_mcp_payload(
                &schema,
                &BTreeMap::from([
                    ("mode".to_owned(), json!("safe")),
                    ("count".to_owned(), json!(3)),
                    ("enabled".to_owned(), json!(true)),
                    ("note".to_owned(), Value::Null),
                ])
            )
            .is_err()
        );
    }

    #[test]
    fn schema_ir_rejects_unsupported_constructs_with_reason_codes() {
        let cases = [
            (
                json!({"type":"object","additionalProperties":false,"unknown":true}),
                "unsupported_keyword",
            ),
            (
                json!({"$schema":"https://json-schema.org/draft/2019-09/schema","type":"object","additionalProperties":false}),
                "unsupported_dialect",
            ),
            (
                json!({"type":"object","properties":{"n":{"type":"number"}},"additionalProperties":false}),
                "unsupported_type",
            ),
            (
                json!({"type":"object","properties":{"x":{"type":"string","enum":["a","a"]}},"additionalProperties":false}),
                "duplicate_enum",
            ),
            (
                json!({"type":"object","properties":{"x":{"type":"string","enum":[1]}},"additionalProperties":false}),
                "enum_type_mismatch",
            ),
            (
                json!({"type":"object","properties":{"x":{"type":"integer","minimum":1.5}},"additionalProperties":false}),
                "malformed_bound",
            ),
            (
                serde_json::from_str::<Value>(r#"{"type":"object","properties":{"x":{"type":"integer","minimum":18446744073709551616}},"additionalProperties":false}"#).expect("huge bound JSON"),
                "malformed_bound",
            ),
            (
                json!({"type":"object","properties":{"x":{"type":"string","default":false}},"additionalProperties":false}),
                "malformed_default",
            ),
            (
                json!({"type":"object","properties":{"x":{"type":"object","properties":{}}},"additionalProperties":false}),
                "unsupported_nested_object",
            ),
            (
                json!({"type":"object","properties":{"x":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}),
                "unsupported_nested_array",
            ),
        ];
        for (schema, reason) in cases {
            let error = adapt_mcp_schema(&schema).expect_err("schema must fail closed");
            assert!(
                error.to_string().contains(reason),
                "{reason} missing from {error}"
            );
        }

        let mut too_many_fields = Map::new();
        for index in 0..=MCP_SCHEMA_MAX_FIELDS {
            too_many_fields.insert(format!("field_{index}"), json!({"type": "string"}));
        }
        let too_many_fields = json!({
            "type": "object",
            "properties": too_many_fields,
            "additionalProperties": false
        });
        let error = adapt_mcp_schema(&too_many_fields).expect_err("field limit");
        assert!(error.to_string().contains("schema_too_large"));

        let too_large = json!({
            "type": "object",
            "description": "x".repeat(MCP_SCHEMA_MAX_BYTES),
            "additionalProperties": false
        });
        let error = adapt_mcp_schema(&too_large).expect_err("byte limit");
        assert!(error.to_string().contains("schema_too_large"));
    }

    #[test]
    fn schema_digest_changes_for_presentation_and_semantic_drift() {
        let first = json!({
            "type":"object",
            "properties":{"mode":{"type":"string","enum":["safe"]}},
            "additionalProperties":false
        });
        let mut second = first.clone();
        second["properties"]["mode"]["enum"] = json!(["unsafe"]);
        assert_ne!(mcp_schema_digest(&first), mcp_schema_digest(&second));
        let mut presentation = first.clone();
        presentation["properties"]["mode"]["title"] = json!("Mode");
        assert_ne!(mcp_schema_digest(&first), mcp_schema_digest(&presentation));
        let first_ir = adapt_mcp_schema(&first).expect("first IR");
        let second_ir = adapt_mcp_schema(&second).expect("second IR");
        assert_ne!(first_ir.source_digest(), second_ir.source_digest());
        let mut identity_only = first.clone();
        identity_only["$id"] = json!("urn:falsegreen:g3:alternate");
        let identity_error = adapt_mcp_schema(&identity_only).expect_err("$id is unsupported");
        assert!(identity_error.to_string().contains("unsupported_keyword"));
        assert!(
            first_ir
                .form_fields()
                .iter()
                .all(|field| !field.label.contains('\n'))
        );
    }

    #[test]
    fn schema_adapter_performance_shapes_are_bounded() {
        use std::time::{Duration, Instant};

        for (label, count) in [
            ("small", 5usize),
            ("medium", 25),
            ("large", 100),
            ("maximum", MCP_SCHEMA_MAX_FIELDS),
        ] {
            let mut properties = Map::new();
            for index in 0..count {
                let name = format!("field_{index}");
                let property = match index % 3 {
                    0 => json!({"type": "string", "minLength": 0, "maxLength": 64}),
                    1 => json!({"type": "integer", "minimum": 0, "maximum": 100}),
                    _ => json!({"type": "boolean"}),
                };
                properties.insert(name, property);
            }
            let schema = json!({
                "type": "object",
                "properties": properties,
                "additionalProperties": false
            });
            let started = Instant::now();
            let ir = adapt_mcp_schema(&schema).expect("performance schema IR");
            let adaptation = started.elapsed();
            let surface = mcp_tool_surface(
                "performance",
                "mcp__fixture__tool__aaaaaaaaaaaaaaaa",
                &schema,
                "state",
            )
            .expect("performance surface");
            let started = Instant::now();
            let rendered =
                render_surface_with_capabilities(&surface, &default_negotiated_capabilities(120))
                    .expect("performance render");
            let rendering = started.elapsed();
            assert_eq!(ir.fields.len(), count);
            assert!(surface.validate_shape(&HostCapabilities::default()).is_ok());
            assert!(!rendered.is_empty());
            eprintln!(
                "G3 schema performance {label}: adapt={adaptation:?}, render_surface={rendering:?}"
            );
        }

        let mut annotation = json!("attacker");
        for _ in 0..5_000 {
            annotation = Value::Array(vec![annotation]);
        }
        let mut deep_object = Map::new();
        deep_object.insert("type".to_owned(), Value::String("object".to_owned()));
        deep_object.insert("additionalProperties".to_owned(), Value::Bool(false));
        deep_object.insert("examples".to_owned(), annotation);
        let deep_schema = Value::Object(deep_object);
        let started = Instant::now();
        let error = adapt_mcp_schema(&deep_schema).expect_err("deep attacker schema");
        let rejection = started.elapsed();
        assert!(error.to_string().contains("schema_depth_exceeded"));
        assert!(
            rejection < Duration::from_secs(1),
            "deep-schema rejection took {rejection:?}"
        );
        std::mem::forget(deep_schema);
    }
}