feat(host-api): add structured result schemas

Author: fffonion

src/compiler/host_call_resolve.rs

@@ -931,6 +931,14 @@ fn schema_label(schema: &crate::host_api::HostTypeSchema) -> String {
         HostTypeSchema::Bytes => "bytes".to_string(),
         HostTypeSchema::Array(inner) => format!("array<{}>", schema_label(inner)),
         HostTypeSchema::Map(inner) => format!("map<{}>", schema_label(inner)),
+        HostTypeSchema::Object(fields) => {
+            let fields = fields
+                .iter()
+                .map(|(name, schema)| format!("{name}: {}", schema_label(schema)))
+                .collect::<Vec<_>>()
+                .join(", ");
+            format!("{{{fields}}}")
+        }
         HostTypeSchema::Optional(inner) => format!("optional<{}>", schema_label(inner)),
         HostTypeSchema::Callable { params, result } => {
             let params = params

src/compiler/host_conversion.rs

@@ -49,6 +49,12 @@ impl HostTypeSchema {
             HostTypeSchema::Bytes => TypeSchema::Bytes,
             HostTypeSchema::Array(inner) => TypeSchema::Array(Box::new(inner.to_compiler_schema())),
             HostTypeSchema::Map(inner) => TypeSchema::Map(Box::new(inner.to_compiler_schema())),
+            HostTypeSchema::Object(fields) => TypeSchema::Object(
+                fields
+                    .iter()
+                    .map(|(name, schema)| (name.clone(), schema.to_compiler_schema()))
+                    .collect(),
+            ),
             HostTypeSchema::Optional(inner) => {
                 TypeSchema::Optional(Box::new(inner.to_compiler_schema()))
             }
@@ -86,9 +92,13 @@ pub(crate) fn to_host_schema(schema: &TypeSchema) -> HostTypeSchema {
             HostTypeSchema::Array(Box::new(to_host_schema(rest)))
         }
         TypeSchema::Map(inner) => HostTypeSchema::Map(Box::new(to_host_schema(inner))),
-        TypeSchema::Object(_) | TypeSchema::Named(_, _) => {
-            HostTypeSchema::Map(Box::new(HostTypeSchema::Unknown))
-        }
+        TypeSchema::Object(fields) => HostTypeSchema::Object(
+            fields
+                .iter()
+                .map(|(name, schema)| (name.clone(), to_host_schema(schema)))
+                .collect(),
+        ),
+        TypeSchema::Named(_, _) => HostTypeSchema::Map(Box::new(HostTypeSchema::Unknown)),
         TypeSchema::Callable { params, result } => HostTypeSchema::Callable {
             params: params.iter().map(to_host_schema).collect(),
             result: Box::new(to_host_schema(result)),
@@ -99,7 +109,10 @@ pub(crate) fn to_host_schema(schema: &TypeSchema) -> HostTypeSchema {
 
 #[cfg(test)]
 mod tests {
+    use std::collections::{BTreeMap, HashMap};
+
     use super::super::TypeSchema;
+    use super::to_host_schema;
     use crate::host_api::HostTypeSchema;
     use crate::host_api::ResourceTypeKey;
 
@@ -161,6 +174,27 @@ mod tests {
         );
     }
 
+    #[test]
+    fn object_schema_round_trips_through_compiler_schema() {
+        let host = HostTypeSchema::Object(BTreeMap::from([
+            (
+                "error".to_string(),
+                HostTypeSchema::Optional(Box::new(HostTypeSchema::String)),
+            ),
+            ("ok".to_string(), HostTypeSchema::Bool),
+        ]));
+        let compiler = TypeSchema::Object(HashMap::from([
+            (
+                "error".to_string(),
+                TypeSchema::Optional(Box::new(TypeSchema::String)),
+            ),
+            ("ok".to_string(), TypeSchema::Bool),
+        ]));
+
+        assert_eq!(host.to_compiler_schema(), compiler);
+        assert_eq!(to_host_schema(&compiler), host);
+    }
+
     #[test]
     fn to_compiler_schema_scalars_are_direct() {
         assert_eq!(

src/compiler/semantic_model.rs

@@ -660,7 +660,14 @@ impl SemanticModel {
             TypeSchema::ArrayTupleRest { prefix: _, rest: _ } => {
                 HostTypeSchema::Array(Box::new(HostTypeSchema::Unknown))
             }
-            TypeSchema::Object(_) => HostTypeSchema::Map(Box::new(HostTypeSchema::Unknown)),
+            TypeSchema::Object(fields) => HostTypeSchema::Object(
+                fields
+                    .iter()
+                    .map(|(name, schema)| {
+                        (name.clone(), self.compiler_schema_to_host_schema(schema))
+                    })
+                    .collect(),
+            ),
         }
     }
 
@@ -1730,6 +1737,8 @@ fn normalize_module_path(path: std::path::PathBuf) -> std::path::PathBuf {
 
 #[cfg(test)]
 mod tests {
+    use std::collections::{BTreeMap, HashMap};
+
     use super::*;
     use crate::compiler::ir::{
         Expr, LocalDeclSite, ParsedCallSite, ParsedCallTarget, ParsedLexicalScope,
@@ -2123,6 +2132,29 @@ mod tests {
     // Signature help
     // ------------------------------------------------------------------
 
+    #[test]
+    fn compiler_schema_to_host_schema_preserves_object_fields() {
+        let model = SemanticModel::new(test_ir(), SourceMap::new(), test_catalog(), Vec::new());
+        let compiler = TypeSchema::Object(HashMap::from([
+            (
+                "error".to_string(),
+                TypeSchema::Optional(Box::new(TypeSchema::String)),
+            ),
+            ("ok".to_string(), TypeSchema::Bool),
+        ]));
+
+        assert_eq!(
+            model.compiler_schema_to_host_schema(&compiler),
+            HostTypeSchema::Object(BTreeMap::from([
+                (
+                    "error".to_string(),
+                    HostTypeSchema::Optional(Box::new(HostTypeSchema::String)),
+                ),
+                ("ok".to_string(), HostTypeSchema::Bool),
+            ]))
+        );
+    }
+
     #[test]
     fn callable_signature_with_no_calls_returns_none() {
         let catalog = test_catalog();

src/host_api.rs

@@ -47,6 +47,7 @@
 //! an attacker can influence catalog bytes. Treat `HostApiFingerprint` as a
 //! convenience equality key, not a MAC.
 
+use std::collections::BTreeMap;
 use std::fmt;
 
 use serde::de::{self, DeserializeSeed, MapAccess, SeqAccess, VariantAccess, Visitor};
@@ -87,6 +88,8 @@ pub const MAX_HOST_CATALOG_FUNCTIONS: usize = 1_024;
 
 /// Maximum byte length of names on host parameter records.
 pub const MAX_HOST_PARAMETER_NAME_LEN: usize = 128;
+/// Maximum byte length of fixed-shape host object field names.
+pub const MAX_HOST_OBJECT_FIELD_NAME_LEN: usize = 128;
 
 /// Maximum byte length of host resource/function documentation.
 pub const MAX_HOST_DESCRIPTION_LEN: usize = 4_096;
@@ -355,6 +358,10 @@ pub enum HostTypeSchema {
     Bytes,
     Array(Box<HostTypeSchema>),
     Map(Box<HostTypeSchema>),
+    /// A fixed-shape record whose field names and value schemas are known.
+    /// Runtime values use the ordinary map carrier, while compilers retain the
+    /// structural field types for checked member access.
+    Object(BTreeMap<String, HostTypeSchema>),
     Optional(Box<HostTypeSchema>),
     Callable {
         params: Vec<HostTypeSchema>,
@@ -425,6 +432,9 @@ impl Serialize for HostTypeSchema {
             Self::Map(inner) => {
                 serializer.serialize_newtype_variant("HostTypeSchema", 9, "Map", inner)
             }
+            Self::Object(fields) => {
+                serializer.serialize_newtype_variant("HostTypeSchema", 13, "Object", fields)
+            }
             Self::Optional(inner) => {
                 serializer.serialize_newtype_variant("HostTypeSchema", 10, "Optional", inner)
             }
@@ -457,6 +467,7 @@ enum HostTypeSchemaVariant {
     Optional,
     Callable,
     Resource,
+    Object,
 }
 
 struct HostTypeSchemaSeed<'a> {
@@ -489,7 +500,7 @@ impl<'de> DeserializeSeed<'de> for HostTypeSchemaSeed<'_> {
             "HostTypeSchema",
             &[
                 "Unknown", "Null", "Int", "Float", "Number", "Bool", "String", "Bytes", "Array",
-                "Map", "Optional", "Callable", "Resource",
+                "Map", "Optional", "Callable", "Resource", "Object",
             ],
             HostTypeSchemaVisitor {
                 budget: self.budget,
@@ -547,6 +558,15 @@ impl<'de> Visitor<'de> for HostTypeSchemaVisitor<'_> {
                     })
                     .map(|inner| HostTypeSchema::Map(Box::new(inner)))
             }
+            HostTypeSchemaVariant::Object => {
+                let depth = next_schema_depth::<A::Error>(self.depth)?;
+                access
+                    .newtype_variant_seed(ObjectSchemaSeed {
+                        budget: self.budget,
+                        depth,
+                    })
+                    .map(HostTypeSchema::Object)
+            }
             HostTypeSchemaVariant::Optional => {
                 let depth = next_schema_depth::<A::Error>(self.depth)?;
                 access
@@ -570,6 +590,67 @@ impl<'de> Visitor<'de> for HostTypeSchemaVisitor<'_> {
     }
 }
 
+struct ObjectSchemaSeed<'a> {
+    budget: &'a mut ComplexityBudget,
+    depth: usize,
+}
+
+impl<'de> DeserializeSeed<'de> for ObjectSchemaSeed<'_> {
+    type Value = BTreeMap<String, HostTypeSchema>;
+
+    fn deserialize<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        deserializer.deserialize_map(ObjectSchemaVisitor {
+            budget: self.budget,
+            depth: self.depth,
+        })
+    }
+}
+
+struct ObjectSchemaVisitor<'a> {
+    budget: &'a mut ComplexityBudget,
+    depth: usize,
+}
+
+impl<'de> Visitor<'de> for ObjectSchemaVisitor<'_> {
+    type Value = BTreeMap<String, HostTypeSchema>;
+
+    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("a bounded fixed-field object schema")
+    }
+
+    fn visit_map<A>(self, mut map: A) -> Result<Self::Value, A::Error>
+    where
+        A: MapAccess<'de>,
+    {
+        bounded_map_size_hint(
+            map.size_hint(),
+            "object schema",
+            MAX_HOST_SCHEMA_PROPERTIES - self.budget.properties,
+        )?;
+        let mut fields = BTreeMap::new();
+        while let Some(name) = map.next_key_seed(BoundedStringSeed {
+            field: "host object field name",
+            limit: MAX_HOST_OBJECT_FIELD_NAME_LEN,
+        })? {
+            if fields.contains_key(&name) {
+                return Err(de::Error::custom(format!(
+                    "duplicate object field {name:?}"
+                )));
+            }
+            let schema = map.next_value_seed(HostTypeSchemaSeed {
+                budget: self.budget,
+                depth: self.depth,
+                property: true,
+            })?;
+            fields.insert(name, schema);
+        }
+        Ok(fields)
+    }
+}
+
 fn next_schema_depth<E>(depth: usize) -> Result<usize, E>
 where
     E: de::Error,
@@ -761,6 +842,16 @@ impl fmt::Display for HostTypeSchema {
             Self::Bytes => write!(f, "bytes"),
             Self::Array(inner) => write!(f, "array<{inner}>"),
             Self::Map(inner) => write!(f, "map<{inner}>"),
+            Self::Object(fields) => {
+                write!(f, "{{")?;
+                for (index, (name, schema)) in fields.iter().enumerate() {
+                    if index > 0 {
+                        write!(f, ", ")?;
+                    }
+                    write!(f, "{name}: {schema}")?;
+                }
+                write!(f, "}}")
+            }
             Self::Optional(inner) => write!(f, "optional<{inner}>"),
             Self::Callable { params, result } => {
                 write!(f, "fn(")?;
@@ -2059,6 +2150,28 @@ where
                 })?;
                 pending.push((inner, child_depth));
             }
+            HostTypeSchema::Object(fields) => {
+                budget.charge_properties(fields.len())?;
+                let child_depth =
+                    depth
+                        .checked_add(1)
+                        .ok_or(HostSchemaValidationError::IntegerOverflow {
+                            field: "schema depth",
+                        })?;
+                pending.try_reserve(fields.len()).map_err(|_| {
+                    HostSchemaValidationError::AllocationFailed {
+                        field: "schema traversal",
+                    }
+                })?;
+                for (name, schema) in fields.iter().rev() {
+                    bounded_string_error(
+                        "host object field name",
+                        name.len(),
+                        MAX_HOST_OBJECT_FIELD_NAME_LEN,
+                    )?;
+                    pending.push((schema, child_depth));
+                }
+            }
             HostTypeSchema::Callable { params, result } => {
                 budget.charge_properties(params.len())?;
                 let child_depth =
@@ -3003,6 +3116,14 @@ fn try_push_type(
                 })?;
                 pending.push(inner);
             }
+            HostTypeSchema::Object(fields) => {
+                push_tag(bytes, b'o');
+                push_len(bytes, fields.len())?;
+                for (name, schema) in fields {
+                    push_len_str(bytes, name)?;
+                    try_push_type(bytes, schema)?;
+                }
+            }
             HostTypeSchema::Optional(inner) => {
                 push_tag(bytes, b'?');
                 pending.try_reserve(1).map_err(|_| {
@@ -3074,9 +3195,53 @@ fn fnv1a(bytes: &[u8]) -> u64 {
 }
 #[cfg(test)]
 mod tests {
+    use std::collections::BTreeMap;
+
     use super::*;
     use serde_json::json;
 
+    #[test]
+    fn object_schema_rejects_oversized_field_names() {
+        let field = "x".repeat(MAX_HOST_OBJECT_FIELD_NAME_LEN + 1);
+        let schema = HostTypeSchema::Object(BTreeMap::from([(field, HostTypeSchema::Bool)]));
+
+        assert_eq!(
+            schema.validate(),
+            Err(HostSchemaValidationError::StringTooLong {
+                field: "host object field name",
+                len: MAX_HOST_OBJECT_FIELD_NAME_LEN + 1,
+                limit: MAX_HOST_OBJECT_FIELD_NAME_LEN,
+            })
+        );
+    }
+
+    #[test]
+    fn object_schema_serde_display_and_resource_walk_are_structural() {
+        let schema = HostTypeSchema::Object(BTreeMap::from([
+            (
+                "handle".to_string(),
+                HostTypeSchema::Optional(Box::new(HostTypeSchema::Resource(io_file_key()))),
+            ),
+            ("ok".to_string(), HostTypeSchema::Bool),
+        ]));
+
+        let encoded = serde_json::to_value(&schema).expect("serialize object schema");
+        let decoded: HostTypeSchema =
+            serde_json::from_value(encoded).expect("deserialize object schema");
+
+        assert_eq!(decoded, schema);
+        assert_eq!(
+            schema.to_string(),
+            "{handle: optional<resource<io.file>>, ok: bool}"
+        );
+        assert!(schema.contains_resource());
+        assert_eq!(schema.resource_key(), None);
+        let mut keys = Vec::new();
+        schema.collect_resource_keys(&mut keys);
+        let expected_key = io_file_key();
+        assert_eq!(keys, vec![&expected_key]);
+    }
+
     fn io_file_key() -> ResourceTypeKey {
         ResourceTypeKey::new("io.file").expect("valid key")
     }