Luigit
repositories / smith

smith

There are many coding harnesses - but this one is fast

owned by admin

smith-core/src/metadata.rs

Raw
//! Typed metadata records and zero-allocation validation (`SMH-SPEC-SPEC0001`).

use serde::de::value::{Error as ValueError, StrDeserializer};
use serde::{Deserialize, Serialize};
use smith::error::MutationState;
use smith::id::{EntryId, ToolCallId};
use smith::structured::{AccessError, Kind, StructuredData, StructuredValue};

use crate::session::{
    COMPACTION_KIND, PLUGIN_HTTP_KIND, PROVIDER_DISPATCH_PROVENANCE_KIND, PROVIDER_HTTP_KIND,
    PROVIDER_TOOL_CALL_IDENTITIES_KIND, TOOL_LOADOUT_PROVENANCE_KIND, TOOL_MUTATION_KIND,
};

/// Bounded lifecycle evidence in existing metadata frames.
pub mod lifecycle;

/// Original delivery intent for a queued notification-window input.
pub const NOTIFICATION_QUEUE_KIND: &str = "notification_queue_admission";

/// Decode bounded notification queue identities without allocating a tree.
///
/// # Errors
/// Rejects unknown, duplicate, absent or malformed fields.
pub fn notification_admission<'a>(
    value: impl StructuredValue<'a>,
) -> Result<crate::control::NotificationAdmission, AccessError> {
    let mut seen = 0u8;
    let mut delivery = None;
    for field in fields(value)? {
        let (name, field) = field?;
        let bit = match name {
            "notifying_root" => {
                lifecycle::identity(value, name)?;
                1
            }
            "submission_id" => {
                lifecycle::identity(value, name)?;
                2
            }
            "source" => {
                scalar::<crate::control::AdmissionSource>(string(field)?)?;
                8
            }
            "delivery" => {
                delivery = Some(scalar::<crate::agent::Delivery>(string(field)?)?);
                4
            }
            _ => return Err(AccessError::Malformed),
        };
        if seen & bit != 0 {
            return Err(AccessError::Malformed);
        }
        seen |= bit;
    }
    if seen != 15 {
        return Err(AccessError::Malformed);
    }
    Ok(crate::control::NotificationAdmission {
        source: crate::control::AdmissionSource::Rpc,
        notifying_root: lifecycle::identity(value, "notifying_root")?,
        submission_id: lifecycle::identity(value, "submission_id")?,
        delivery: delivery.ok_or(AccessError::Malformed)?,
    })
}

/// Durable terminal failure observed after a completed outer effect.
pub const INVOCATION_TERMINAL_STOP_KIND: &str = "invocation-terminal-stop";

/// Completed effects remain evidence; this later stop prevents root continuation.
#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InvocationTerminalStop {
    /// Admitted root, absent for trusted host invocation outside admission.
    pub submission_id: Option<EntryId>,
    /// Completed outer call that incurred this cleanup cost.
    pub call_id: ToolCallId,
    /// Host failure, not a falsified guest or primitive result.
    pub reason: crate::tools::InvocationStop,
    /// Latest bounded observation before this evidence is encoded.
    pub allocation: crate::tools::InvocationAllocationReport,
}

/// Maximum independently observable effects in one outer invocation.
pub const NESTED_EFFECTS_MAX: u16 = 64;
/// Maximum inline redacted nested argument or result bytes; small-path wire stays unchanged.
pub const NESTED_EFFECT_BYTES_MAX: usize = 64 * 1024;
/// Maximum logical nested input or output, stored as same-ledger immutable chunks.
/// Covers 1 MiB binary HTTP at worst 20x credential-redacted hex plus metadata.
pub const NESTED_PAYLOAD_BYTES_MAX: usize = 32 * 1024 * 1024;
/// One physical chunk, independent of the unchanged 1 MiB frame ceiling.
pub const NESTED_CHUNK_BYTES_MAX: usize = 64 * 1024;
/// Derived count ceiling per input or output, not a history-resident index.
pub const NESTED_CHUNKS_MAX: usize = NESTED_PAYLOAD_BYTES_MAX / NESTED_CHUNK_BYTES_MAX;

/// Exact logical length of contiguous, owner-validated preceding payload chunks.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct NestedPayloadRef {
    /// Full canonical redacted UTF-8 byte length; count derives by ceiling division.
    pub payload_bytes: u32,
}

/// Inline evidence or a complete same-ledger chunk reference.
#[derive(Debug, Serialize)]
#[serde(untagged)]
pub enum NestedPayload<'a> {
    /// Existing small-path encoding.
    Inline(&'a str),
    /// Large-path reference, never a digest or truncated value.
    Chunks(NestedPayloadRef),
}
/// Durable intent before an independently observable guest effect.
pub const NESTED_INTENT_KIND: &str = "nested-effect-intent";
/// Atomic effect completion and root progress checkpoint.
pub const NESTED_COMPLETION_KIND: &str = "nested-effect-completion";

/// Explicit synchronous causality, independent of chronological entry parents.
/// Effect IDs are host-issued intent entry IDs; invocation records are nonmutating.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct NestedCausality {
    /// Stable intent identity, repeated by its completion.
    pub effect_id: EntryId,
    /// Enclosing invocation intent, absent at the outer tool boundary.
    pub parent: Option<EntryId>,
    /// True only for host orchestration, never an external primitive effect.
    pub invocation: bool,
}

/// Explicit causal extension; legacy records retain their wire and memory layout.
#[derive(Debug, Serialize, Deserialize)]
pub struct CausalRecord<Record> {
    /// Unchanged primitive evidence vocabulary.
    #[serde(flatten)]
    pub record: Record,
    /// Required explicit causal identity.
    pub causal: NestedCausality,
}

/// Encode either legacy flat evidence or explicit composed evidence.
pub(crate) fn encode_nested<Record: Serialize>(
    record: Record,
    causal: Option<&NestedCausality>,
) -> smith::Result<StructuredData> {
    match causal {
        Some(causal) => encode(&CausalRecord {
            record,
            causal: *causal,
        }),
        None => encode(&record),
    }
}

/// One bounded guest effect's durable identity and redacted input.
#[derive(Debug, Serialize)]
pub struct NestedEffectIntent<'a, Input = &'a str> {
    /// Admitted root owning this effect.
    pub submission_id: EntryId,
    /// Outer tool invocation, never a tool name surrogate.
    pub call_id: ToolCallId,
    /// Zero-based ordinal within that invocation.
    pub index: u16,
    /// Host mechanism selected after capability checks.
    pub operation: &'a str,
    /// Exact component generation, absent only for native fixture dispatchers.
    pub component: Option<&'a crate::tools::ToolComponentProvenance>,
    /// Redacted canonical argument evidence.
    pub input: Input,
}

/// Completion and root progress advance together in one required frame.
#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct NestedEffectCompletion<Output = String> {
    /// Admitted root owning this effect.
    pub submission_id: EntryId,
    /// Outer invocation.
    pub call_id: ToolCallId,
    /// Completed ordinal; next ordinal is derived, never duplicated.
    pub index: u16,
    /// Success is independent of mutation evidence.
    pub ok: bool,
    /// Best known effect outcome.
    pub mutation_state: MutationState,
    /// Redacted bounded result or error.
    pub output: Output,
}

/// One tool completion's durable mutation state.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ToolMutationMetadata {
    /// Identifier of the completed tool call.
    pub call_id: ToolCallId,
    /// Best-known host mutation outcome.
    pub mutation_state: MutationState,
}

impl ToolMutationMetadata {
    /// A typed mutation record.
    #[must_use]
    pub const fn new(call_id: ToolCallId, mutation_state: MutationState) -> Self {
        Self {
            call_id,
            mutation_state,
        }
    }
}

/// One provider-owned identity paired with a Smith tool call.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ProviderToolCallIdentityMetadata {
    /// Smith's durable tool-call identity.
    pub call_id: ToolCallId,
    /// Provider identity required to replay this call in later requests.
    pub provider_call_id: String,
}

/// A persisted compaction summary.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct CompactionMetadata {
    /// Summary text.
    pub summary: String,
    /// Whether the producer knew the summary was complete.
    #[serde(
        default,
        deserialize_with = "deserialize_complete",
        skip_serializing_if = "Option::is_none"
    )]
    pub complete: Option<bool>,
}

fn deserialize_complete<'de, D: serde::Deserializer<'de>>(
    deserializer: D,
) -> Result<Option<bool>, D::Error> {
    bool::deserialize(deserializer).map(Some)
}

/// Encode a typed metadata record as structured data.
///
/// # Errors
///
/// Returns `ENTRY_DECODE` when the record cannot be represented as structured data.
pub fn encode<Record: Serialize>(record: &Record) -> smith::Result<StructuredData> {
    StructuredData::from_serializable(record).map_err(|error| smith::SmithError::Session {
        code: smith::error::SessionCode::EntryDecode,
        message: format!("cannot encode metadata: {error}"),
    })
}

/// Validate a reserved metadata record without materializing its structured tree.
///
/// Unknown extension kinds remain unrestricted structured data.
///
/// # Errors
///
/// Returns [`AccessError::Malformed`] when a reserved kind has an invalid shape.
pub fn validate<'a, Value: StructuredValue<'a>>(
    kind: &str,
    value: Value,
) -> Result<(), AccessError> {
    match kind {
        NOTIFICATION_QUEUE_KIND => notification_admission(value).map(|_| ()),
        lifecycle::INVOCATION_INTENT
        | lifecycle::INVOCATION_COMPLETION
        | lifecycle::EFFECT_INTENT
        | lifecycle::EFFECT_COMPLETION => lifecycle::validate(kind, value),
        INVOCATION_TERMINAL_STOP_KIND => invocation_terminal_stop(value),
        NESTED_INTENT_KIND => nested_effect(value, false),
        NESTED_COMPLETION_KIND => nested_effect(value, true),
        COMPACTION_KIND => compaction(value),
        TOOL_MUTATION_KIND => tool_mutation(value),
        TOOL_LOADOUT_PROVENANCE_KIND => tool_loadout_provenance(value),
        PROVIDER_HTTP_KIND => provider_effect(value),
        PLUGIN_HTTP_KIND => plugin_http_effect(value),
        PROVIDER_DISPATCH_PROVENANCE_KIND => provider_dispatch_provenance(value),
        PROVIDER_TOOL_CALL_IDENTITIES_KIND => provider_tool_call_identity(value),
        _ => Ok(()),
    }
}

fn fields<'a, Value: StructuredValue<'a>>(value: Value) -> Result<Value::Fields, AccessError> {
    value.fields()?.ok_or(AccessError::Malformed)
}

fn string<'a, Value: StructuredValue<'a>>(value: Value) -> Result<&'a str, AccessError> {
    match value.kind()? {
        Kind::String(value) => Ok(value),
        _ => Err(AccessError::Malformed),
    }
}

fn boolean<'a, Value: StructuredValue<'a>>(value: Value) -> Result<bool, AccessError> {
    match value.kind()? {
        Kind::Bool(value) => Ok(value),
        _ => Err(AccessError::Malformed),
    }
}

fn unsigned<'a, Value: StructuredValue<'a>>(value: Value) -> Result<u64, AccessError> {
    match value.kind()? {
        Kind::Unsigned(value) => Ok(value),
        Kind::Signed(value) if value >= 0 => Ok(value.cast_unsigned()),
        _ => Err(AccessError::Malformed),
    }
}

fn scalar<'a, Record: Deserialize<'a>>(value: &str) -> Result<Record, AccessError> {
    Record::deserialize(StrDeserializer::<ValueError>::new(value))
        .map_err(|_| AccessError::Malformed)
}

fn compaction<'a, Value: StructuredValue<'a>>(value: Value) -> Result<(), AccessError> {
    let mut summary = false;
    for field in fields(value)? {
        let (name, value) = field?;
        match name {
            "summary" => {
                string(value)?;
                summary = true;
            }
            "complete" => {
                boolean(value)?;
            }

            _ => {}
        }
    }
    summary.then_some(()).ok_or(AccessError::Malformed)
}

pub(crate) fn nested_identity<'a>(
    value: impl StructuredValue<'a>,
) -> Result<(EntryId, ToolCallId, u16), AccessError> {
    let root: EntryId = scalar(string(
        value
            .field("submission_id")?
            .ok_or(AccessError::Malformed)?,
    )?)?;
    let call: ToolCallId = scalar(string(
        value.field("call_id")?.ok_or(AccessError::Malformed)?,
    )?)?;
    let index = u16::try_from(unsigned(
        value.field("index")?.ok_or(AccessError::Malformed)?,
    )?)
    .map_err(|_| AccessError::Malformed)?;
    if root.as_u128() == 0 || call.as_u128() == 0 || index >= NESTED_EFFECTS_MAX {
        return Err(AccessError::Malformed);
    }
    Ok((root, call, index))
}

pub(crate) fn nested_causality<'a>(
    value: impl StructuredValue<'a>,
) -> Result<Option<NestedCausality>, AccessError> {
    let Some(value) = value.field("causal")? else {
        return Ok(None);
    };
    let mut effect = None;
    let mut parent = None;
    let mut invocation = None;
    for field in fields(value)? {
        let (name, value) = field?;
        match name {
            "effect_id" if effect.is_none() => effect = Some(scalar::<EntryId>(string(value)?)?),
            "parent" if parent.is_none() => {
                parent = Some(match value.kind()? {
                    Kind::Null => None,
                    _ => Some(scalar::<EntryId>(string(value)?)?),
                });
            }
            "invocation" if invocation.is_none() => invocation = Some(boolean(value)?),
            _ => return Err(AccessError::Malformed),
        }
    }
    let causal = NestedCausality {
        effect_id: effect.ok_or(AccessError::Malformed)?,
        parent: parent.ok_or(AccessError::Malformed)?,
        invocation: invocation.ok_or(AccessError::Malformed)?,
    };
    if causal.effect_id.as_u128() == 0
        || causal
            .parent
            .is_some_and(|parent| parent.as_u128() == 0 || parent == causal.effect_id)
    {
        return Err(AccessError::Malformed);
    }
    Ok(Some(causal))
}

pub(crate) fn nested_payload_ref<'a>(
    value: impl StructuredValue<'a>,
) -> Result<Option<NestedPayloadRef>, AccessError> {
    if let Kind::String(text) = value.kind()? {
        return (text.len() <= NESTED_EFFECT_BYTES_MAX)
            .then_some(None)
            .ok_or(AccessError::Malformed);
    }
    let mut bytes = None;
    for field in fields(value)? {
        let (name, value) = field?;
        if name != "payload_bytes" || bytes.is_some() {
            return Err(AccessError::Malformed);
        }
        let length = usize::try_from(unsigned(value)?).map_err(|_| AccessError::Malformed)?;
        if !(NESTED_EFFECT_BYTES_MAX + 1..=NESTED_PAYLOAD_BYTES_MAX).contains(&length) {
            return Err(AccessError::Malformed);
        }
        bytes = Some(NestedPayloadRef {
            payload_bytes: u32::try_from(length).map_err(|_| AccessError::Malformed)?,
        });
    }
    bytes.map(Some).ok_or(AccessError::Malformed)
}

fn validate_nested_payload<'a>(value: impl StructuredValue<'a>) -> Result<(), AccessError> {
    nested_payload_ref(value).map(|_| ())
}

fn nested_effect<'a>(value: impl StructuredValue<'a>, completion: bool) -> Result<(), AccessError> {
    nested_identity(value)?;
    let causal = nested_causality(value)?;
    let mut seen = 0u8;
    for field in fields(value)? {
        let (name, value) = field?;
        let bit = match name {
            "causal" => 64,
            "submission_id" => 1,
            "call_id" => 2,
            "index" => 4,
            "ok" if completion => {
                boolean(value)?;
                8
            }
            "mutation_state" if completion => {
                let mutation: MutationState = scalar(string(value)?)?;
                if causal.is_some_and(|causal| causal.invocation)
                    && mutation != MutationState::NotApplied
                {
                    return Err(AccessError::Malformed);
                }
                16
            }
            "operation" if !completion => {
                let operation = string(value)?;
                if operation.is_empty() || operation.len() > 128 {
                    return Err(AccessError::Malformed);
                }
                8
            }
            "component" if !completion => {
                if !matches!(value.kind()?, Kind::Null) {
                    component_provenance(value)?;
                }
                16
            }
            "output" if completion => {
                validate_nested_payload(value)?;
                32
            }
            "input" if !completion => {
                validate_nested_payload(value)?;
                32
            }
            _ => return Err(AccessError::Malformed),
        };
        if seen & bit != 0 {
            return Err(AccessError::Malformed);
        }
        seen |= bit;
    }
    (seen == 63 || seen == 127)
        .then_some(())
        .ok_or(AccessError::Malformed)
}

fn invocation_terminal_stop<'a, Value: StructuredValue<'a>>(
    value: Value,
) -> Result<(), AccessError> {
    exact_fields(value, &["submission_id", "call_id", "reason", "allocation"])?;
    let submission = required(value, "submission_id")?;
    if !matches!(submission.kind()?, Kind::Null) {
        let _: EntryId = scalar(string(submission)?)?;
    }
    let _: ToolCallId = scalar(string(required(value, "call_id")?)?)?;
    let reason: crate::tools::InvocationStop = scalar(string(required(value, "reason")?)?)?;
    if reason != crate::tools::InvocationStop::HostAllocation {
        return Err(AccessError::Malformed);
    }
    let allocation = required(value, "allocation")?;
    exact_fields(
        allocation,
        &[
            "threshold_bytes",
            "actual_bytes",
            "cleanup_bytes",
            "excess_bytes",
            "allocations",
            "stopped_bytes",
        ],
    )?;
    let threshold = unsigned(required(allocation, "threshold_bytes")?)?;
    let actual = unsigned(required(allocation, "actual_bytes")?)?;
    let cleanup = unsigned(required(allocation, "cleanup_bytes")?)?;
    let excess = unsigned(required(allocation, "excess_bytes")?)?;
    let _allocations = unsigned(required(allocation, "allocations")?)?;
    let stopped = unsigned(required(allocation, "stopped_bytes")?)?;
    (threshold > 0
        && actual > threshold
        && excess == actual - threshold
        && cleanup <= actual
        && stopped > threshold
        && stopped <= actual)
        .then_some(())
        .ok_or(AccessError::Malformed)
}

fn tool_mutation<'a, Value: StructuredValue<'a>>(value: Value) -> Result<(), AccessError> {
    let mut call_id = false;
    let mut mutation_state = false;
    for field in fields(value)? {
        let (name, value) = field?;
        match name {
            "call_id" if !call_id => {
                let _: ToolCallId = scalar(string(value)?)?;
                call_id = true;
            }
            "mutation_state" if !mutation_state => {
                let _: MutationState = scalar(string(value)?)?;
                mutation_state = true;
            }
            _ => return Err(AccessError::Malformed),
        }
    }
    (call_id && mutation_state)
        .then_some(())
        .ok_or(AccessError::Malformed)
}

fn required<'a, Value: StructuredValue<'a>>(
    value: Value,
    name: &str,
) -> Result<Value, AccessError> {
    value.field(name)?.ok_or(AccessError::Malformed)
}

fn exact_fields<'a, Value: StructuredValue<'a>>(
    value: Value,
    expected: &[&str],
) -> Result<(), AccessError> {
    let fields = fields(value)?;
    if fields.len() != expected.len() {
        return Err(AccessError::Malformed);
    }
    for field in fields {
        let (name, _) = field?;
        if !expected.contains(&name) {
            return Err(AccessError::Malformed);
        }
    }
    Ok(())
}

fn tool_loadout_provenance<'a, Value: StructuredValue<'a>>(
    value: Value,
) -> Result<(), AccessError> {
    exact_fields(value, &["components", "tools"])?;
    let components = required(value, "components")?
        .elements()?
        .ok_or(AccessError::Malformed)?;
    if components.len() > 1_024 {
        return Err(AccessError::Malformed);
    }
    let component_count = components.len();
    for component in components {
        let component = component?;
        component_provenance(component)?;
    }
    let tools = required(value, "tools")?
        .elements()?
        .ok_or(AccessError::Malformed)?;
    if tools.len() > 1_024 {
        return Err(AccessError::Malformed);
    }
    for tool in tools {
        let tool = tool?;
        exact_fields(tool, &["definition", "component_index"])?;
        let definition = required(tool, "definition")?;
        exact_fields(definition, &["name", "description", "input_schema"])?;
        if string(required(definition, "name")?)?.is_empty()
            || string(required(definition, "description")?)?.is_empty()
            || matches!(required(definition, "input_schema")?.kind()?, Kind::Null)
            || usize::try_from(unsigned(required(tool, "component_index")?)?)
                .map_err(|_| AccessError::Malformed)?
                >= component_count
        {
            return Err(AccessError::Malformed);
        }
    }
    Ok(())
}

fn component_provenance<'a>(component: impl StructuredValue<'a>) -> Result<(), AccessError> {
    exact_fields(
        component,
        &["source_id", "manifest_sha256", "component_sha256"],
    )?;
    let source_id = string(required(component, "source_id")?)?;
    if source_id.is_empty()
        || source_id.len() > 256
        || !valid_sha256(string(required(component, "manifest_sha256")?)?)
        || !valid_sha256(string(required(component, "component_sha256")?)?)
    {
        return Err(AccessError::Malformed);
    }
    Ok(())
}

fn valid_sha256(value: &str) -> bool {
    value.len() == 64
        && value
            .bytes()
            .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
}

fn provider_tool_call_identity<'a, Value: StructuredValue<'a>>(
    value: Value,
) -> Result<(), AccessError> {
    exact_fields(value, &["call_id", "provider_call_id"])?;
    let _: ToolCallId = scalar(string(required(value, "call_id")?)?)?;
    let provider_call_id = string(required(value, "provider_call_id")?)?;
    if provider_call_id.is_empty()
        || provider_call_id.len() > crate::session::PROVIDER_CALL_ID_BYTES_MAX
    {
        return Err(AccessError::Malformed);
    }
    Ok(())
}

fn provider_dispatch_provenance<'a, Value: StructuredValue<'a>>(
    value: Value,
) -> Result<(), AccessError> {
    let binding = value.field("credential_binding")?;
    let registration = value.field("registration_binding")?;
    let mut names = [
        "connection_id",
        "protocol_manifest_id",
        "protocol_component_sha256",
        "catalog_generation",
        "catalog_source",
        "settings",
        "credential_binding",
        "registration_binding",
    ];
    let mut count = 6;
    if binding.is_some() {
        count += 1;
    }
    if registration.is_some() {
        names[count] = "registration_binding";
        count += 1;
    }
    exact_fields(value, &names[..count])?;
    if let Some(registration) = registration {
        exact_fields(
            registration,
            &["provider_id", "model_id", "credential_source_id"],
        )?;
        for name in ["provider_id", "model_id", "credential_source_id"] {
            let identity = string(required(registration, name)?)?;
            if identity.is_empty() || identity.len() > 512 {
                return Err(AccessError::Malformed);
            }
        }
    }
    if let Some(binding) = binding {
        exact_fields(binding, &["module_id", "profile_id"])?;
        let module = string(required(binding, "module_id")?)?;
        if module.is_empty()
            || module.len() > 256
            || !valid_sha256(string(required(binding, "profile_id")?)?)
        {
            return Err(AccessError::Malformed);
        }
    }
    for name in ["connection_id", "protocol_manifest_id"] {
        let value = string(required(value, name)?)?;
        if value.is_empty() || value.len() > 256 {
            return Err(AccessError::Malformed);
        }
    }
    let digest = string(required(value, "protocol_component_sha256")?)?;
    if !valid_sha256(digest) {
        return Err(AccessError::Malformed);
    }
    unsigned(required(value, "catalog_generation")?)?;
    let _: smith::provider::ProviderCatalogSource =
        scalar(string(required(value, "catalog_source")?)?)?;
    let settings = required(value, "settings")?;
    exact_fields(settings, &["include_usage", "provenance"])?;
    boolean(required(settings, "include_usage")?)?;
    let _: smith::provider::ProviderSettingsProvenance =
        scalar(string(required(settings, "provenance")?)?)?;
    Ok(())
}

fn provider_effect<'a, Value: StructuredValue<'a>>(value: Value) -> Result<(), AccessError> {
    match string(required(value, "phase")?)? {
        "intent" => {
            exact_fields(
                value,
                &["phase", "method", "url", "headers", "request_bytes"],
            )?;
            if !matches!(string(required(value, "method")?)?, "POST" | "GET") {
                return Err(AccessError::Malformed);
            }
            string(required(value, "url")?)?;
            usize::try_from(unsigned(required(value, "request_bytes")?)?)
                .map_err(|_| AccessError::Malformed)?;
            let headers = required(value, "headers")?
                .elements()?
                .ok_or(AccessError::Malformed)?;
            for header in headers {
                header_fields(header?)?;
            }
        }
        "outcome" => {
            exact_fields(value, &["phase", "status", "response_bytes", "outcome"])?;
            u16::try_from(unsigned(required(value, "status")?)?)
                .map_err(|_| AccessError::Malformed)?;
            unsigned(required(value, "response_bytes")?)?;
            let _: smith::provider::ProviderEffectOutcome =
                scalar(string(required(value, "outcome")?)?)?;
        }
        _ => return Err(AccessError::Malformed),
    }
    Ok(())
}

fn plugin_http_effect<'a, Value: StructuredValue<'a>>(value: Value) -> Result<(), AccessError> {
    match string(required(value, "phase")?)? {
        "intent" => {
            exact_fields(
                value,
                &[
                    "phase",
                    "plugin_id",
                    "call_id",
                    "origin",
                    "method",
                    "headers",
                    "request_bytes",
                    "timeout_ms",
                    "response_bytes_max",
                ],
            )?;
            for name in ["plugin_id", "origin"] {
                let text = string(required(value, name)?)?;
                if text.is_empty() || text.len() > 4_096 {
                    return Err(AccessError::Malformed);
                }
            }
            let _: ToolCallId = scalar(string(required(value, "call_id")?)?)?;
            let _: smith::http::HttpMethod = scalar(string(required(value, "method")?)?)?;
            usize::try_from(unsigned(required(value, "request_bytes")?)?)
                .map_err(|_| AccessError::Malformed)?;
            unsigned(required(value, "timeout_ms")?)?;
            unsigned(required(value, "response_bytes_max")?)?;
            let headers = required(value, "headers")?
                .elements()?
                .ok_or(AccessError::Malformed)?;
            for header in headers {
                header_fields(header?)?;
            }
        }
        "outcome" => {
            exact_fields(value, &["phase", "status", "response_bytes", "outcome"])?;
            u16::try_from(unsigned(required(value, "status")?)?)
                .map_err(|_| AccessError::Malformed)?;
            unsigned(required(value, "response_bytes")?)?;
            let _: smith::http::PluginHttpEffectOutcome =
                scalar(string(required(value, "outcome")?)?)?;
        }
        _ => return Err(AccessError::Malformed),
    }
    Ok(())
}

fn header_fields<'a, Value: StructuredValue<'a>>(value: Value) -> Result<(), AccessError> {
    let mut name = false;
    let mut header_value = false;
    for field in fields(value)? {
        let (field_name, field_value) = field?;
        match field_name {
            "name" if !name => {
                string(field_value)?;
                name = true;
            }
            "value" if !header_value => {
                string(field_value)?;
                header_value = true;
            }
            "name" | "value" => return Err(AccessError::Malformed),
            _ => {}
        }
    }
    (name && header_value)
        .then_some(())
        .ok_or(AccessError::Malformed)
}

#[cfg(test)]
mod tests {
    //! SMH-SPEC-SPEC0001: Shared structured data.
    #[test]
    fn terminal_cleanup_stop_requires_causal_identity_and_actual_excess() {
        use super::*;
        let record = InvocationTerminalStop {
            submission_id: Some(EntryId::from_u128(1)),
            call_id: ToolCallId::from_u128(2),
            reason: crate::tools::InvocationStop::HostAllocation,
            allocation: crate::tools::InvocationAllocationReport {
                threshold_bytes: 100,
                actual_bytes: 125,
                cleanup_bytes: 75,
                excess_bytes: 25,
                allocations: 3,
                stopped_bytes: Some(125),
            },
        };
        assert_eq!(std::mem::size_of::<InvocationTerminalStop>(), 96);
        assert!(
            validate(
                INVOCATION_TERMINAL_STOP_KIND,
                encode(&record).unwrap().view()
            )
            .is_ok()
        );
        let original = serde_json::to_value(&record).unwrap();
        for (field, value) in [
            ("threshold_bytes", 0),
            ("actual_bytes", 100),
            ("excess_bytes", 0),
            ("cleanup_bytes", 126),
            ("stopped_bytes", 100),
            ("stopped_bytes", 126),
        ] {
            let mut invalid = original.clone();
            invalid["allocation"][field] = value.into();
            let invalid = smith::StructuredData::from_serializable(&invalid).unwrap();
            assert!(
                validate(INVOCATION_TERMINAL_STOP_KIND, invalid.view()).is_err(),
                "{field}={value}"
            );
        }
        let mut invalid = original;
        invalid["call_id"] = "not an identity".into();
        assert!(
            validate(
                INVOCATION_TERMINAL_STOP_KIND,
                smith::StructuredData::from_serializable(&invalid)
                    .unwrap()
                    .view()
            )
            .is_err()
        );
    }

    use super::*;

    #[cfg(target_arch = "x86_64")]
    #[test]
    fn metadata_layouts_are_exact() {
        assert_eq!(std::mem::size_of::<ToolMutationMetadata>(), 17);
        assert_eq!(std::mem::size_of::<CompactionMetadata>(), 32);
        assert_eq!(std::mem::size_of::<ProviderToolCallIdentityMetadata>(), 40);
    }

    #[test]
    fn compaction_record_deserialization_matches_present_boolean_shape() {
        let legacy: CompactionMetadata = serde_json::from_str(r#"{"summary":"x"}"#).unwrap();
        assert_eq!(legacy.complete, None);
        assert!(
            serde_json::from_str::<CompactionMetadata>(r#"{"summary":"x","complete":null}"#)
                .is_err()
        );
        let complete: CompactionMetadata =
            serde_json::from_str(r#"{"summary":"x","complete":true}"#).unwrap();
        assert_eq!(complete.complete, Some(true));
    }

    #[test]
    fn known_metadata_accepts_owned_shapes() {
        let call_id = ToolCallId::from_u128(1);
        for (kind, detail) in [
            (
                COMPACTION_KIND,
                StructuredData::from_json(r#"{"summary":"legacy"}"#).unwrap(),
            ),
            (
                TOOL_MUTATION_KIND,
                encode(&ToolMutationMetadata::new(call_id, MutationState::Applied))
                .unwrap(),
            ),
            (
                PROVIDER_HTTP_KIND,
                StructuredData::from_json(r#"{"phase":"intent","method":"POST","url":"","headers":[{"name":"n","value":"v","extension":null}],"request_bytes":0}"#).unwrap(),
            ),
            (
                PROVIDER_HTTP_KIND,
                StructuredData::from_json(r#"{"phase":"outcome","status":0,"response_bytes":0,"outcome":"cancelled"}"#).unwrap(),
            ),
            (
                PLUGIN_HTTP_KIND,
                StructuredData::from_serializable(&smith::http::PluginHttpEffectRecord::Intent {
                    plugin_id: "example:plugin".to_string(),
                    call_id,
                    origin: "https://api.example.test".to_string(),
                    method: smith::http::HttpMethod::Post,
                    headers: vec![smith::http::HttpHeader {
                        name: "Authorization".to_string(),
                        value: "<redacted>".to_string(),
                    }]
                    .into(),
                    request_bytes: 0,
                    timeout_ms: 1,
                    response_bytes_max: 1,
                })
                .unwrap(),
            ),
            (
                PLUGIN_HTTP_KIND,
                StructuredData::from_serializable(&smith::http::PluginHttpEffectRecord::Outcome {
                    status: 0,
                    response_bytes: 0,
                    outcome: smith::http::PluginHttpEffectOutcome::Failed,
                })
                .unwrap(),
            ),
            (
                PROVIDER_DISPATCH_PROVENANCE_KIND,
                StructuredData::from_json(r#"{"connection_id":"zai-api","protocol_manifest_id":"smith:protocol-openai-compatible","protocol_component_sha256":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","catalog_generation":0,"catalog_source":"bundled","settings":{"include_usage":true,"provenance":"built_in"}}"#).unwrap(),
            ),
            (
                PROVIDER_TOOL_CALL_IDENTITIES_KIND,
                encode(&ProviderToolCallIdentityMetadata {
                    call_id,
                    provider_call_id: "vendor".to_string(),
                })
                .unwrap(),
            ),
            ("extension", StructuredData::from_json(r#"[false,{"any":"shape"}]"#).unwrap()),
        ] {
            assert!(validate(kind, detail.view()).is_ok(), "rejected {kind}");
        }
    }

    #[test]
    fn selected_credential_binding_validates_only_bounded_metadata_references() {
        let mut record = serde_json::json!({"connection_id":"openai-chatgpt-plan","protocol_manifest_id":"smith:protocol-openai-responses","protocol_component_sha256":"a".repeat(64),"catalog_generation":0,"catalog_source":"bundled","settings":{"include_usage":true,"provenance":"built_in"},"credential_binding":{"module_id":"openai-chatgpt-plan@1","profile_id":"b".repeat(64)}});
        let detail = StructuredData::from_serializable(&record).unwrap();
        assert!(validate(PROVIDER_DISPATCH_PROVENANCE_KIND, detail.view()).is_ok());
        for invalid in [
            serde_json::json!(null),
            serde_json::json!({"module_id":"","profile_id":"b".repeat(64)}),
            serde_json::json!({"module_id":"x".repeat(257),"profile_id":"b".repeat(64)}),
            serde_json::json!({"module_id":"openai-chatgpt-plan@1","profile_id":"invalid"}),
            serde_json::json!({"module_id":"openai-chatgpt-plan@1","profile_id":"b".repeat(64),"token":"must never be accepted"}),
        ] {
            record["credential_binding"] = invalid;
            let detail = StructuredData::from_serializable(&record).unwrap();
            assert!(validate(PROVIDER_DISPATCH_PROVENANCE_KIND, detail.view()).is_err());
        }
    }

    #[test]
    fn registered_selection_accepts_only_bounded_identity_metadata_with_optional_credentials() {
        let mut record = serde_json::json!({"connection_id":"fixture","protocol_manifest_id":"example:fixture","protocol_component_sha256":"a".repeat(64),"catalog_generation":1,"catalog_source":"cache","settings":{"include_usage":true,"provenance":"explicit"}});
        let binding = serde_json::json!({"provider_id":"x".repeat(512),"model_id":"example:fixture/model","credential_source_id":"example:fixture/source"});
        for credential in [false, true] {
            if credential {
                record["credential_binding"] =
                    serde_json::json!({"module_id":"fixture@1","profile_id":"b".repeat(64)});
            }
            record["registration_binding"] = binding.clone();
            let detail = StructuredData::from_serializable(&record).unwrap();
            assert!(validate(PROVIDER_DISPATCH_PROVENANCE_KIND, detail.view()).is_ok());
            for invalid in [
                serde_json::json!(null),
                serde_json::json!({}),
                serde_json::json!({"provider_id":"x","model_id":"m","credential_source_id":"s","token":"forbidden"}),
            ] {
                record["registration_binding"] = invalid;
                let detail = StructuredData::from_serializable(&record).unwrap();
                assert!(validate(PROVIDER_DISPATCH_PROVENANCE_KIND, detail.view()).is_err());
            }
            for field in ["provider_id", "model_id", "credential_source_id"] {
                for invalid in [
                    serde_json::json!(""),
                    serde_json::json!("x".repeat(513)),
                    serde_json::json!(false),
                ] {
                    record["registration_binding"] = binding.clone();
                    record["registration_binding"][field] = invalid;
                    let detail = StructuredData::from_serializable(&record).unwrap();
                    assert!(validate(PROVIDER_DISPATCH_PROVENANCE_KIND, detail.view()).is_err());
                }
            }
        }
    }

    #[test]
    fn known_metadata_rejects_malformed_owned_shapes() {
        let call_id = ToolCallId::from_u128(1);
        let valid_call_id = serde_json::to_string(&call_id).unwrap();
        let invalid = [
            (COMPACTION_KIND, r#"{}"#.to_string()),
            (COMPACTION_KIND, r#"{"summary":null}"#.to_string()),
            (COMPACTION_KIND, r#"{"summary":"x","complete":null}"#.to_string()),
            (TOOL_MUTATION_KIND, r#"{}"#.to_string()),
            (TOOL_MUTATION_KIND, format!(r#"{{"call_id":{valid_call_id}}}"#)),
            (TOOL_MUTATION_KIND, r#"{"mutation_state":"applied"}"#.to_string()),
            (TOOL_MUTATION_KIND, format!(r#"{{"call_id":{valid_call_id},"mutation_state":"applied","extra":true}}"#)),
            (TOOL_MUTATION_KIND, r#"{"call_id":"bad","mutation_state":"applied"}"#.to_string()),
            (TOOL_MUTATION_KIND, format!(r#"{{"call_id":{valid_call_id},"mutation_state":"wrong"}}"#)),
            (PROVIDER_HTTP_KIND, r#"{"method":"POST","url":"x","headers":[],"request_bytes":0}"#.to_string()),
            (PROVIDER_HTTP_KIND, r#"{"phase":"intent","method":"DELETE","url":"x","headers":[],"request_bytes":0}"#.to_string()),
            (PROVIDER_HTTP_KIND, r#"{"phase":"intent","method":"POST","url":"x","headers":[null],"request_bytes":0}"#.to_string()),
            (PROVIDER_HTTP_KIND, r#"{"phase":"intent","method":"POST","url":"x","headers":[{"name":false,"value":"v"}],"request_bytes":0}"#.to_string()),
            (PROVIDER_HTTP_KIND, r#"{"phase":"intent","method":"POST","url":"x","headers":[],"request_bytes":18446744073709551615,"extra":true}"#.to_string()),
            (PROVIDER_HTTP_KIND, r#"{"phase":"outcome","status":65536,"response_bytes":0,"outcome":"completed"}"#.to_string()),
            (PROVIDER_HTTP_KIND, r#"{"phase":"outcome","status":0,"response_bytes":-1,"outcome":"completed"}"#.to_string()),
            (PROVIDER_HTTP_KIND, r#"{"phase":"outcome","status":0,"response_bytes":0,"outcome":"completed","extra":true}"#.to_string()),
            (PROVIDER_DISPATCH_PROVENANCE_KIND, r#"{"connection_id":"zai-api","protocol_manifest_id":"smith:protocol-openai-compatible","protocol_component_sha256":"bad","catalog_generation":0,"catalog_source":"bundled","settings":{"include_usage":true,"provenance":"built_in"}}"#.to_string()),
            (PROVIDER_DISPATCH_PROVENANCE_KIND, r#"{"connection_id":"zai-api","protocol_manifest_id":"smith:protocol-openai-compatible","protocol_component_sha256":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","catalog_generation":0,"catalog_source":"bundled","settings":{"include_usage":true,"provenance":"unknown"}}"#.to_string()),
            (PROVIDER_TOOL_CALL_IDENTITIES_KIND, r#"{}"#.to_string()),
            (PROVIDER_TOOL_CALL_IDENTITIES_KIND, format!(r#"{{"call_id":{valid_call_id},"provider_call_id":""}}"#)),
            (PROVIDER_TOOL_CALL_IDENTITIES_KIND, format!(r#"{{"call_id":{valid_call_id},"provider_call_id":"vendor","extra":true}}"#)),
        ];
        for (kind, detail) in invalid {
            let detail = StructuredData::from_json(&detail).unwrap();
            assert!(
                validate(kind, detail.view()).is_err(),
                "accepted {kind}: {detail:?}"
            );
        }
    }
}