Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

refactor(schema): bind parameter contracts to registry entries

Steven Enamakelb0649863254e
diff --git a/crates/openhuman-core/src/core/schema_test_support.rs b/crates/openhuman-core/src/core/schema_test_support.rs
index 0ee593b2d6..8f7054027f 100644
--- a/crates/openhuman-core/src/core/schema_test_support.rs
+++ b/crates/openhuman-core/src/core/schema_test_support.rs
@@ -1,20 +1,20 @@
use super::*;
-/// Independent wire fixtures paired with the handler's real pure decoder.
-/// The runner checks parameter acceptance and never invokes the handler.
+/// Independently authored wire fixtures checked against an actual bound
+/// registry entry. The runner validates examples with the production schema
+/// and decoder, but never invokes its gate or business handler.
#[derive(Clone)]
pub(crate) struct ControllerParamContract {
pub method: &'static str,
pub required: &'static [&'static str],
- pub handler: ControllerHandler,
+ pub optional: &'static [&'static str],
pub examples: Vec<Value>,
- pub parse: fn(Map<String, Value>) -> Result<(), String>,
}
/// Select controllers independently of the fixture table, so a missing fixture
/// cannot silently remove its own controller from the check.
pub(crate) fn verify_parameter_contracts(
- controllers: &[RegisteredController],
+ controllers: &[ControllerEntry],
contracts: &[ControllerParamContract],
) -> Result<(), String> {
use std::collections::BTreeMap;
@@ -45,12 +45,19 @@ pub(crate) fn verify_parameter_contracts(
}
for (method, controller) in registered {
let contract = by_method[method.as_str()];
- if !std::ptr::fn_addr_eq(controller.handler, contract.handler) {
- return Err(format!(
- "{method} handler identity differs from its contract"
- ));
+ if !controller.is_bound() {
+ return Err(format!("{method} registry entry is legacy, not bound"));
}
verify_parameter_schema(&controller.schema, contract)?;
+ for (index, example) in contract.examples.iter().enumerate() {
+ let params = example
+ .as_object()
+ .expect("schema verifier rejects non-object examples")
+ .clone();
+ controller.decode_params(params).map_err(|error| {
+ format!("{method} bound decoder rejects example {index}: {error}")
+ })?;
+ }
}
Ok(())
}
@@ -69,6 +76,7 @@ pub(crate) fn verify_parameter_schema(
return Err(format!("{} has no description", contract.method));
}
required_input_contract(schema, contract.required)?;
+ optional_input_contract(schema, contract.optional)?;
if contract.examples.is_empty() {
return Err(format!("{} has no examples", contract.method));
}
@@ -82,16 +90,30 @@ pub(crate) fn verify_parameter_schema(
contract.method
)
})?;
- (contract.parse)(params.clone()).map_err(|error| {
- format!(
- "{} pure parser rejects example {index}: {error}",
- contract.method
- )
- })?;
}
Ok(())
}
+pub(crate) fn optional_input_contract(
+ schema: &ControllerSchema,
+ optional: &[&str],
+) -> Result<(), String> {
+ let actual: Vec<_> = schema
+ .inputs
+ .iter()
+ .filter(|field| !field.required)
+ .map(|field| field.name)
+ .collect();
+ if actual == optional {
+ Ok(())
+ } else {
+ Err(format!(
+ "{}.{} optional inputs mismatch: expected {optional:?}, got {actual:?}",
+ schema.namespace, schema.function
+ ))
+ }
+}
+
/// Owner-authored namespace literals must cover the complete family, including
/// methods without their own field contract; parity alone is self-derived.
pub(crate) fn expect_schema_namespace(schemas: &[ControllerSchema], expected: &str) {
diff --git a/crates/openhuman-core/src/mcp/registry/schemas/mod.rs b/crates/openhuman-core/src/mcp/registry/schemas/mod.rs
index 68d06ad02b..6c895eb6c0 100644
--- a/crates/openhuman-core/src/mcp/registry/schemas/mod.rs
+++ b/crates/openhuman-core/src/mcp/registry/schemas/mod.rs
@@ -52,13 +52,3 @@ pub(crate) fn registry_get_controller_entry() -> ControllerEntry {
#[cfg(test)]
use params::{read_optional_u32, read_required};
-#[cfg(test)]
-pub(crate) fn registry_get_parameter_contract() -> crate::core::all::ControllerParamContract {
- crate::core::all::ControllerParamContract {
- method: "mcp_clients.registry_get",
- required: &["qualified_name"],
- handler: handlers::handle_registry_get,
- examples: vec![serde_json::json!({"qualified_name":"example/server"})],
- parse: |params| handlers::parse_registry_get(&params).map(drop),
- }
-}
diff --git a/crates/openhuman-core/src/modules/schemas.rs b/crates/openhuman-core/src/modules/schemas.rs
index 599def3ef2..60a60df0aa 100644
--- a/crates/openhuman-core/src/modules/schemas.rs
+++ b/crates/openhuman-core/src/modules/schemas.rs
@@ -363,20 +363,3 @@ fn computer_status_controller_entry() -> ControllerEntry {
))
}
-#[cfg(test)]
-pub(crate) fn computer_status_parameter_contract() -> crate::core::all::ControllerParamContract {
- crate::core::all::ControllerParamContract {
- method: "modules.computer_status",
- required: &[],
- handler: handle_computer_status,
- examples: vec![
- serde_json::json!({}),
- serde_json::json!({"load":false}),
- serde_json::json!({"load":true}),
- ],
- parse: |params| {
- let _ = computer_status_load(&params);
- Ok(())
- },
- }
-}
diff --git a/crates/openhuman-core/src/voice/live/schema_parameter_contracts.rs b/crates/openhuman-core/src/voice/live/schema_parameter_contracts.rs
index d602e7313e..ffa8da7116 100644
--- a/crates/openhuman-core/src/voice/live/schema_parameter_contracts.rs
+++ b/crates/openhuman-core/src/voice/live/schema_parameter_contracts.rs
@@ -1,47 +1,34 @@
-use super::*;
use crate::core::all::ControllerParamContract;
use serde_json::json;
-fn decode<T: serde::de::DeserializeOwned>(params: Map<String, Value>) -> Result<(), String> {
- parse_params::<T>(params).map(drop)
-}
-
-fn ignored(_params: Map<String, Value>) -> Result<(), String> {
- Ok(())
-}
-
pub(crate) fn contracts() -> Vec<ControllerParamContract> {
vec![
ControllerParamContract {
method: "voice.live_providers",
required: &[],
- handler: handle_live_providers,
+ optional: &[],
examples: vec![json!({})],
- parse: ignored,
},
ControllerParamContract {
method: "voice.live_settings_get",
required: &[],
- handler: handle_live_settings_get,
+ optional: &[],
examples: vec![json!({})],
- parse: ignored,
},
ControllerParamContract {
method: "voice.live_settings_set",
required: &[],
- handler: handle_live_settings_set,
+ optional: &["default_provider", "gemini", "sarvam", "elevenlabs"],
examples: vec![
json!({}),
json!({"default_provider":"gemini","gemini":{"model":"fixture","voice":null},"sarvam":{"language":"en"},"elevenlabs":{"voice_id":"fixture"}}),
],
- parse: decode::<LiveSettingsPatch>,
},
ControllerParamContract {
method: "voice.live_test_provider",
required: &["provider"],
- handler: handle_live_test_provider,
+ optional: &[],
examples: vec![json!({"provider":"gemini"})],
- parse: decode::<TestParams>,
},
]
}
diff --git a/crates/openhuman-core/src/voice/schemas/parameter_contracts.rs b/crates/openhuman-core/src/voice/schemas/parameter_contracts.rs
index b1cc605038..9d50eeb0d8 100644
--- a/crates/openhuman-core/src/voice/schemas/parameter_contracts.rs
+++ b/crates/openhuman-core/src/voice/schemas/parameter_contracts.rs
@@ -1,127 +1,105 @@
-use super::handlers::*;
-use super::params::*;
use crate::core::all::ControllerParamContract;
-use serde::de::DeserializeOwned;
-use serde_json::{json, Map, Value};
+use serde_json::json;
-fn decode<T: DeserializeOwned>(params: Map<String, Value>) -> Result<(), String> {
- super::helpers::deserialize_params::<T>(params).map(drop)
-}
-
-fn ignored(_params: Map<String, Value>) -> Result<(), String> {
- Ok(())
-}
-
-/// Explicit parameter fixtures; decoder types match the named handlers.
+/// Independent parameter fixtures for the production-bound voice entries.
/// Domain-specific defaults, values and errors remain in schemas_tests.rs.
pub(crate) fn contracts() -> Vec<ControllerParamContract> {
let mut contracts = vec![
ControllerParamContract {
method: "voice.status",
required: &[],
- handler: handle_voice_status,
+ optional: &[],
examples: vec![json!({})],
- parse: ignored,
},
ControllerParamContract {
method: "voice.transcribe",
required: &["audio_path"],
- handler: handle_voice_transcribe,
+ optional: &["context", "skip_cleanup"],
examples: vec![
json!({"audio_path":"fixture.wav"}),
json!({"audio_path":"fixture.wav","context":"example","skip_cleanup":true}),
],
- parse: decode::<TranscribeParams>,
},
ControllerParamContract {
method: "voice.transcribe_bytes",
required: &["audio_bytes"],
- handler: handle_voice_transcribe_bytes,
+ optional: &["extension", "context", "skip_cleanup"],
examples: vec![
json!({"audio_bytes":[0,1]}),
json!({"audio_bytes":[0,1],"extension":"wav","context":"example","skip_cleanup":true}),
],
- parse: decode::<TranscribeBytesParams>,
},
ControllerParamContract {
method: "voice.tts",
required: &["text"],
- handler: handle_voice_tts,
+ optional: &["output_path"],
examples: vec![
json!({"text":"Hello"}),
json!({"text":"Hello","output_path":"fixture.wav"}),
],
- parse: decode::<TtsParams>,
},
ControllerParamContract {
method: "voice.reply_synthesize",
required: &["text"],
- handler: handle_voice_reply_synthesize,
+ optional: &["voice_id", "model_id", "output_format"],
examples: vec![
json!({"text":"Hello"}),
json!({"text":"Hello","voice_id":"fixture","model_id":"fixture","output_format":"mp3_44100"}),
],
- parse: decode::<ReplySynthesizeParams>,
},
ControllerParamContract {
method: "voice.stt_dispatch",
required: &["audio_base64"],
- handler: handle_voice_stt_dispatch,
+ optional: &["provider", "model", "mime_type", "file_name", "language"],
examples: vec![
json!({"audio_base64":"AA=="}),
json!({"audio_base64":"AA==","provider":"cloud","model":"fixture","mime_type":"audio/wav","file_name":"fixture.wav","language":"en"}),
],
- parse: decode::<SttDispatchParams>,
},
ControllerParamContract {
method: "voice.tts_dispatch",
required: &["text"],
- handler: handle_voice_tts_dispatch,
+ optional: &["provider", "voice"],
examples: vec![
json!({"text":"Hello"}),
json!({"text":"Hello","provider":"cloud","voice":"fixture"}),
],
- parse: decode::<TtsDispatchParams>,
},
ControllerParamContract {
method: "voice.set_providers",
required: &[],
- handler: handle_voice_set_providers,
+ optional: &["stt_provider", "tts_provider", "stt_model", "tts_voice"],
examples: vec![
json!({}),
json!({"stt_provider":"cloud","tts_provider":"cloud","stt_model":"fixture","tts_voice":"fixture"}),
],
- parse: decode::<SetProvidersParams>,
},
ControllerParamContract {
method: "voice.update_provider_settings",
required: &[],
- handler: handle_voice_update_provider_settings,
+ optional: &["voice_providers", "stt_provider", "tts_provider"],
examples: vec![
json!({}),
json!({"voice_providers":[{"slug":"fixture-provider"}],"stt_provider":"cloud","tts_provider":"cloud"}),
],
- parse: decode::<VoiceUpdateProviderSettingsParams>,
},
ControllerParamContract {
method: "voice.list_models",
required: &["provider_id"],
- handler: handle_voice_list_models,
+ optional: &["capability"],
examples: vec![
json!({"provider_id":"fixture"}),
json!({"provider_id":"fixture","capability":"stt"}),
],
- parse: decode::<VoiceListModelsParams>,
},
ControllerParamContract {
method: "voice.test_provider",
required: &["workload", "provider"],
- handler: handle_voice_test_provider,
+ optional: &["validate_only", "api_key"],
examples: vec![
json!({"workload":"tts","provider":"cloud"}),
json!({"workload":"stt","provider":"cloud","validate_only":true,"api_key":"fixture-key"}),
],
- parse: decode::<VoiceTestProviderParams>,
},
];
contracts.extend(crate::voice::live::schemas::parameter_contracts());