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:?}"
);
}
}
}