fix: enforce boundary contracts for API response shape and multi-spec resolution

unwrap_response now returns Result — a missing wrapper key is a typed
error instead of a silent fallback to the entire body. json_response_to_batch
rejects unexpected JSON shapes (null, bool, number, string) instead of
returning empty results. find_table renamed to find_tables, returns all
matches across catalogs so bare names in multi-spec mode surface every
matching table with its spec prefix. MCP instructions and get_schema
advertise qualified names in multi-spec mode. Example clippy lint
suppression added to fix CI --all-targets.

Author: benaiad

crates/sqlize-core/examples/github_schema.rs

@@ -1,3 +1,9 @@
+#![expect(
+    clippy::print_stdout,
+    clippy::expect_used,
+    reason = "example binary, stdout is the interface"
+)]
+
 use std::path::Path;
 
 use sqlize_core::catalog::ddl::catalog_ddl;

crates/sqlize-core/src/datafusion/arrow_convert.rs

@@ -93,7 +93,20 @@ pub fn json_response_to_batch(
     let items = match json {
         serde_json::Value::Array(arr) => arr.as_slice(),
         serde_json::Value::Object(_) => std::slice::from_ref(json),
-        _ => &[],
+        other => {
+            return Err(DataFusionError::External(Box::new(std::io::Error::other(
+                format!(
+                    "expected JSON array or object from API, got {}",
+                    match other {
+                        serde_json::Value::Null => "null",
+                        serde_json::Value::Bool(_) => "boolean",
+                        serde_json::Value::Number(_) => "number",
+                        serde_json::Value::String(_) => "string",
+                        _ => unreachable!(),
+                    }
+                ),
+            ))));
+        }
     };
 
     // Build key map once from the first item (O(keys) instead of O(rows * cols * keys))
@@ -496,4 +509,27 @@ mod tests {
         let batch = json_response_to_batch(&json, &cols, &params, &schema).unwrap();
         assert!(batch.column(0).is_null(0));
     }
+
+    #[test]
+    fn unexpected_json_shape_is_error() {
+        let cols = vec![response_col("title", ColumnType::String)];
+        let table = test_table(cols.clone());
+        let schema = virtual_table_to_schema(&table);
+        let params = HashMap::new();
+
+        for (json, expected_label) in [
+            (serde_json::Value::Null, "null"),
+            (serde_json::Value::Bool(true), "boolean"),
+            (serde_json::json!(42), "number"),
+            (serde_json::json!("a string"), "string"),
+        ] {
+            let err = json_response_to_batch(&json, &cols, &params, &schema)
+                .expect_err(&format!("expected error for JSON {expected_label}"));
+            let msg = err.to_string();
+            assert!(
+                msg.contains(expected_label),
+                "error for {expected_label} should mention the type, got: {msg}"
+            );
+        }
+    }
 }

crates/sqlize-core/src/datafusion/exec.rs

@@ -201,7 +201,10 @@ impl ExecutionPlan for ApiTableExec {
                 Err(e) => return Some((Err(e), state)),
             };
 
-            let data = unwrap_response(&body, &state.table.endpoint.response_wrapper_key);
+            let data = match unwrap_response(&body, &state.table.endpoint.response_wrapper_key) {
+                Ok(d) => d,
+                Err(e) => return Some((Err(e), state)),
+            };
 
             let batch = match json_response_to_batch(
                 data,
@@ -327,9 +330,44 @@ async fn fetch_page(
 fn unwrap_response<'a>(
     body: &'a serde_json::Value,
     wrapper_key: &Option<String>,
-) -> &'a serde_json::Value {
+) -> Result<&'a serde_json::Value, DataFusionError> {
     match wrapper_key {
-        Some(field) => body.get(field.as_str()).unwrap_or(body),
-        None => body,
+        Some(field) => body.get(field.as_str()).ok_or_else(|| {
+            DataFusionError::External(Box::new(std::io::Error::other(format!(
+                "response missing expected wrapper field '{field}'"
+            ))))
+        }),
+        None => Ok(body),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn unwrap_response_no_key_returns_body() {
+        let body = serde_json::json!({"items": [1, 2, 3]});
+        let result = unwrap_response(&body, &None).unwrap();
+        assert_eq!(result, &body);
+    }
+
+    #[test]
+    fn unwrap_response_valid_key_extracts_inner() {
+        let body = serde_json::json!({"items": [1, 2, 3], "total": 3});
+        let result = unwrap_response(&body, &Some("items".to_owned())).unwrap();
+        assert_eq!(result, &serde_json::json!([1, 2, 3]));
+    }
+
+    #[test]
+    fn unwrap_response_missing_key_is_error() {
+        let body = serde_json::json!({"data": [1, 2, 3]});
+        let err = unwrap_response(&body, &Some("items".to_owned()))
+            .expect_err("should fail when wrapper key is absent");
+        let msg = err.to_string();
+        assert!(
+            msg.contains("items"),
+            "error should name the missing field, got: {msg}"
+        );
     }
 }

crates/sqlize/src/mcp.rs

@@ -21,10 +21,17 @@ pub struct SqlizeServer {
 
 impl SqlizeServer {
     pub fn new(catalog_set: Arc<CatalogSet>, ctx: Arc<QueryEngine>, api_title: &str) -> Self {
+        let multi = catalog_set.is_multi();
         let table_names: Vec<String> = catalog_set
             .all_tables()
             .iter()
-            .map(|(_, t)| t.name.as_str().to_owned())
+            .map(|(schema, t)| {
+                if multi {
+                    format!("{schema}.{}", t.name)
+                } else {
+                    t.name.as_str().to_owned()
+                }
+            })
             .collect();
         let instructions = format!(
             "SQLize: Query the {api_title} using SQL.\n\
@@ -76,31 +83,43 @@ impl SqlizeServer {
             if let Some(ddl) = self.catalog_set.describe(name) {
                 ddl
             } else {
+                let multi = self.catalog_set.is_multi();
                 let available: Vec<String> = self
                     .catalog_set
                     .all_tables()
                     .iter()
-                    .map(|(_, t)| t.name.as_str().to_owned())
+                    .map(|(schema, t)| {
+                        if multi {
+                            format!("{schema}.{}", t.name)
+                        } else {
+                            t.name.as_str().to_owned()
+                        }
+                    })
                     .collect();
                 format!(
                     "Table '{name}' not found. Available tables:\n{}",
                     available.join(", ")
                 )
             }
         } else {
+            let multi = self.catalog_set.is_multi();
             let mut out = String::from(
                 "Available tables (use get_schema with a table name for full DDL):\n\n",
             );
-            for (_, table) in self.catalog_set.all_tables() {
+            for (schema, table) in self.catalog_set.all_tables() {
+                let display_name = if multi {
+                    format!("{schema}.{}", table.name)
+                } else {
+                    table.name.as_str().to_owned()
+                };
                 let required: Vec<_> = table.required_params().map(|c| c.name.as_str()).collect();
                 let req = if required.is_empty() {
                     String::new()
                 } else {
                     format!("  required: {}", required.join(", "))
                 };
                 out.push_str(&format!(
-                    "  {:<30} -- {}{}\n",
-                    table.name,
+                    "  {display_name:<30} -- {}{}\n",
                     table
                         .description
                         .as_ref()

crates/sqlize/src/repl.rs

@@ -59,42 +59,51 @@ impl CatalogSet {
         tables
     }
 
-    /// Look up a table by name. Supports "schema.table" or bare "table" (searches all).
-    pub fn find_table(&self, name: &str) -> Option<(&str, &VirtualTable)> {
+    /// Look up tables by name. Supports "schema.table" (exact) or bare "table" (all catalogs).
+    pub fn find_tables(&self, name: &str) -> Vec<(&str, &VirtualTable)> {
         if let Some((schema, table)) = name.split_once('.') {
-            // Qualified: schema.table
-            for (cat_name, catalog) in &self.entries {
-                if cat_name == schema {
-                    if let Ok(tn) = TableName::new(table) {
-                        if let Some(t) = catalog.get(&tn) {
-                            return Some((cat_name, t));
-                        }
-                    }
-                }
-            }
-            None
+            // Qualified: schema.table — at most one match
+            let Ok(tn) = TableName::new(table) else {
+                return Vec::new();
+            };
+            self.entries
+                .iter()
+                .filter(|(cat_name, _)| cat_name == schema)
+                .filter_map(|(cat_name, catalog)| catalog.get(&tn).map(|t| (cat_name.as_str(), t)))
+                .collect()
         } else {
-            // Bare: search all catalogs
-            if let Ok(tn) = TableName::new(name) {
-                for (cat_name, catalog) in &self.entries {
-                    if let Some(t) = catalog.get(&tn) {
-                        return Some((cat_name, t));
-                    }
-                }
-            }
-            None
+            // Bare: return all matches across catalogs
+            let Ok(tn) = TableName::new(name) else {
+                return Vec::new();
+            };
+            self.entries
+                .iter()
+                .filter_map(|(cat_name, catalog)| catalog.get(&tn).map(|t| (cat_name.as_str(), t)))
+                .collect()
         }
     }
 
     pub fn describe(&self, name: &str) -> Option<String> {
-        self.find_table(name).map(|(_, t)| table_ddl(t))
+        let matches = self.find_tables(name);
+        if matches.is_empty() {
+            return None;
+        }
+        if matches.len() == 1 && !self.is_multi() {
+            return Some(table_ddl(matches[0].1));
+        }
+        // Multiple matches or multi-spec mode: prefix each with spec name
+        let ddls: Vec<String> = matches
+            .iter()
+            .map(|(schema, t)| format!("-- Spec: {schema}\n{}", table_ddl(t)))
+            .collect();
+        Some(ddls.join("\n\n"))
     }
 
     pub fn full_ddl(&self) -> String {
         let mut out = String::new();
         for (name, catalog) in &self.entries {
             if self.is_multi() {
-                out.push_str(&format!("-- Schema: {name}\n\n"));
+                out.push_str(&format!("-- Spec: {name}\n\n"));
             }
             out.push_str(&catalog_ddl(catalog));
             out.push('\n');
@@ -539,7 +548,7 @@ fn handle_show_tables(catalog_set: &CatalogSet) {
     let mut builder = Builder::default();
 
     if catalog_set.is_multi() {
-        builder.push_record(["schema", "table", "columns", "required", "description"]);
+        builder.push_record(["spec", "table", "columns", "required", "description"]);
     } else {
         builder.push_record(["table", "columns", "required", "description"]);
     }