Add Wardwright provider adapter docs

Author: bglusman

README.md

@@ -28,7 +28,7 @@ potions than Howl would tolerate.
 | Command-line and optional MCP tools for agent-facing secret-name discovery, with no value readback | Working | [Agent-facing tools](https://calciforge.org/#agent-facing-tools-mcp-and-cli) |
 | Agent runtime contract for command-line guidance, optional MCP, artifacts, and future Calciforge APIs | Working draft | [Agent runtime contract](docs/agent-runtime-contract.md) |
 | Telegram, Matrix, WhatsApp, Signal, and text/iMessage routing | Working | [Multi-channel chat](https://calciforge.org/#multi-channel-chat) |
-| OpenAI-compatible model gateway, provider routing, model aliases, alloys, cascades, dispatchers, and local model switching | Working | [Model gateway](docs/model-gateway.md) |
+| OpenAI-compatible model gateway, provider routing, model aliases, Wardwright adapter support, legacy alloys/cascades/dispatchers, and local model switching | Working | [Model gateway](docs/model-gateway.md) |
 | Helicone-backed gateway observability with dashboard-visible doctor checks | Working | [Model gateway](docs/model-gateway.md#external-gateway-engines) |
 | Codex CLI and OpenClaw Codex subscription/OAuth integration paths | Working | [Codex integration](docs/codex-openclaw-integration.md) |
 | `calciforge doctor` config/state/endpoint diagnostics | Working | [Quick Start](#quick-start) |
@@ -124,8 +124,10 @@ tunnel with `CALCIFORGE_PASTE_PUBLIC_BASE_URL`.
 
 Keep Calciforge's own service traffic separate from agent traffic. Point
 agents at Calciforge's OpenAI-compatible model gateway for model calls;
-that path provides model aliases, alloys, cascades, dispatchers, provider
-routing, and observability. Route agent tool/web traffic through
+that path provides model aliases, provider routing, observability, and legacy
+in-process synthetic selectors. For new alloys, cascades, and dispatchers, use
+[Wardwright](https://wardwright.dev/) as an OpenAI-compatible provider adapter
+and let it own the route graph and receipts. Route agent tool/web traffic through
 `security-proxy` or a Calciforge fetch/tool integration when returned
 content needs scanning or `{{secret:NAME}}` substitution.
 

crates/calciforge/src/config.rs

@@ -63,18 +63,27 @@ pub struct CalciforgeConfig {
     #[serde(default)]
     pub model_roles: Vec<ModelRoleConfig>,
 
-    /// `[[alloys]]` — model blending/mixing groups.
+    /// `[[alloys]]` — legacy in-process model blending/mixing groups.
+    ///
+    /// Kept for compatibility. New synthetic-model composition should live in
+    /// Wardwright or another OpenAI-compatible provider adapter.
     /// Use `!model <alloy-id>` to activate an alloy for an identity.
     #[serde(default)]
     pub alloys: Vec<AlloyConfig>,
 
-    /// `[[cascades]]` — explicit ordered model fallback chains.
+    /// `[[cascades]]` — legacy explicit ordered model fallback chains.
+    ///
+    /// Kept for compatibility. New fallback graphs should live in Wardwright
+    /// or another OpenAI-compatible provider adapter.
     /// The proxy tries the first model whose declared context window can hold
     /// the request, then falls through to later eligible models on failure.
     #[serde(default)]
     pub cascades: Vec<CascadeConfig>,
 
-    /// `[[dispatchers]]` — request-size aware model selectors.
+    /// `[[dispatchers]]` — legacy request-size aware model selectors.
+    ///
+    /// Kept for compatibility. New request-shape routing should live in
+    /// Wardwright or another OpenAI-compatible provider adapter.
     /// The proxy picks the smallest configured model that can hold the request,
     /// then uses larger eligible models as fallbacks.
     #[serde(default)]
@@ -149,7 +158,10 @@ impl CalciforgeConfig {
     }
 }
 
-/// Alloy definition (`[[alloys]]`).
+/// Legacy alloy definition (`[[alloys]]`).
+///
+/// Calciforge still executes this for existing configs. Prefer Wardwright for
+/// new synthetic-model composition.
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct AlloyConfig {
     /// Alloy identifier used by commands (e.g. "free-alloy-1").
@@ -192,7 +204,10 @@ fn default_alloy_weight() -> u32 {
     1
 }
 
-/// Cascade definition (`[[cascades]]`).
+/// Legacy cascade definition (`[[cascades]]`).
+///
+/// Calciforge still executes this for existing configs. Prefer Wardwright for
+/// new synthetic-model composition.
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct CascadeConfig {
     /// Synthetic model id requested by agents.
@@ -205,7 +220,10 @@ pub struct CascadeConfig {
     pub models: Vec<SyntheticModelConfig>,
 }
 
-/// Dispatcher definition (`[[dispatchers]]`).
+/// Legacy dispatcher definition (`[[dispatchers]]`).
+///
+/// Calciforge still executes this for existing configs. Prefer Wardwright for
+/// new synthetic-model composition.
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct DispatcherConfig {
     /// Synthetic model id requested by agents.
@@ -1077,8 +1095,8 @@ pub struct ProxyProviderConfig {
 
     /// Provider adapter kind. Supported OpenAI-compatible engine overlays
     /// include "http", "helicone", "litellm", "portkey", "tensorzero",
-    /// "future-agi", and "openrouter". They share the same request core;
-    /// the kind chooses engine metadata, dashboard capability, and any
+    /// "future-agi", "openrouter", and "wardwright". They share the same
+    /// request core; the kind chooses engine metadata, dashboard capability, and any
     /// provider-specific headers. CLI-backed subscriptions are configured as
     /// `[[agents]]`, not gateway providers.
     #[serde(default = "default_proxy_provider_backend")]

crates/calciforge/src/config/validator.rs

@@ -71,6 +71,8 @@ pub fn validate_config(config: &CalciforgeConfig) -> ValidationResult {
     // Validate enabled channels before long-lived tasks start.
     validate_channels(config, &mut result);
 
+    warn_on_legacy_synthetic_selectors(config, &mut result);
+
     // Validate alloys have valid constituents
     validate_alloys(config, &mut result);
 
@@ -90,6 +92,17 @@ pub fn validate_config(config: &CalciforgeConfig) -> ValidationResult {
     result
 }
 
+fn warn_on_legacy_synthetic_selectors(config: &CalciforgeConfig, result: &mut ValidationResult) {
+    let has_legacy_synthetic_selectors =
+        !config.alloys.is_empty() || !config.cascades.is_empty() || !config.dispatchers.is_empty();
+    if has_legacy_synthetic_selectors {
+        result.add_warning(
+            "Calciforge in-process synthetic selectors ([[alloys]], [[cascades]], [[dispatchers]]) are legacy compatibility features. Prefer Wardwright or another OpenAI-compatible provider adapter for new synthetic-model composition."
+                .to_string(),
+        );
+    }
+}
+
 /// Validate agent adapter kinds and required fields.
 fn validate_agents(config: &CalciforgeConfig, result: &mut ValidationResult) {
     for agent in &config.agents {

crates/calciforge/src/config/validator_tests_3.rs

@@ -376,6 +376,7 @@ fn named_openai_compatible_backend_types_are_validated_from_shared_allowlist() {
         "tensorzero",
         "future-agi",
         "openrouter",
+        "wardwright",
     ] {
         let fixture = format!(
             "{MIN_VALID}\n[proxy]\nenabled = true\nbind = \"127.0.0.1:18083\"\nbackend_type = \"{backend_type}\"\nbackend_url = \"https://gateway.example.invalid/v1\"\n"
@@ -390,6 +391,30 @@ fn named_openai_compatible_backend_types_are_validated_from_shared_allowlist() {
     }
 }
 
+#[test]
+fn legacy_synthetic_selectors_warn_to_prefer_wardwright() {
+    let fixture = format!(
+        "{MIN_VALID}\n[[dispatchers]]\nid = \"balanced\"\nname = \"Balanced\"\n\n[[dispatchers.models]]\nmodel = \"local-small\"\ncontext_window = 32000\n"
+    );
+    let config = parse(&fixture);
+    let result = validate_config(&config);
+
+    assert!(
+        result.is_valid(),
+        "legacy synthetic selectors should remain valid while migration is optional: {:?}",
+        result.errors
+    );
+    assert!(
+        result
+            .warnings
+            .iter()
+            .any(|warning| warning.contains("legacy compatibility")
+                && warning.contains("Wardwright")),
+        "synthetic selector configs should point operators toward Wardwright; warnings: {:?}",
+        result.warnings
+    );
+}
+
 #[test]
 fn root_backend_type_aliases_validate_with_runtime_parser() {
     for backend_type in ["direct", "builtin_http", "lite_llm", "open_router"] {

crates/calciforge/src/proxy/backend.rs

@@ -279,6 +279,7 @@ impl SecretsBackend for MockBackend {
                 total_tokens: 0,
             },
             system_fingerprint: None,
+            extra_body: serde_json::Map::new(),
         })
     }
 

crates/calciforge/src/proxy/gateway.rs

@@ -3,7 +3,7 @@
 //! Calciforge should not assume there is one installed "model gateway". It owns
 //! a policy/audit/auth boundary, then routes to one or more configured provider
 //! adapters such as builtin OpenAI-compatible HTTP, Helicone, LiteLLM,
-//! OpenRouter, Ollama, or mock test adapters.
+//! OpenRouter, Wardwright, Ollama, or mock test adapters.
 //!
 //! The older config field names still say `backend_type` for compatibility, but
 //! runtime code should treat these as adapter kinds.
@@ -136,6 +136,8 @@ pub enum GatewayType {
     FutureAgi,
     /// OpenRouter OpenAI-compatible provider boundary.
     OpenRouter,
+    /// Wardwright synthetic model gateway.
+    Wardwright,
     /// Mock adapter for tests only.
     Mock,
 }
@@ -152,6 +154,7 @@ impl std::str::FromStr for GatewayType {
             "tensorzero" | "tensor-zero" | "tensor_zero" => Ok(GatewayType::TensorZero),
             "future-agi" | "future_agi" | "futureagi" => Ok(GatewayType::FutureAgi),
             "openrouter" | "open-router" | "open_router" => Ok(GatewayType::OpenRouter),
+            "wardwright" | "ward-wright" | "ward_wright" => Ok(GatewayType::Wardwright),
             "mock" => Ok(GatewayType::Mock),
             _ => Err(format!("Unknown gateway type: {}", s)),
         }
@@ -168,6 +171,7 @@ impl std::fmt::Display for GatewayType {
             GatewayType::TensorZero => write!(f, "tensorzero"),
             GatewayType::FutureAgi => write!(f, "future-agi"),
             GatewayType::OpenRouter => write!(f, "openrouter"),
+            GatewayType::Wardwright => write!(f, "wardwright"),
             GatewayType::Mock => write!(f, "mock"),
         }
     }
@@ -182,6 +186,7 @@ impl GatewayType {
         "tensorzero",
         "future-agi",
         "openrouter",
+        "wardwright",
         "mock",
     ];
 
@@ -193,6 +198,7 @@ impl GatewayType {
         "tensorzero",
         "future-agi",
         "openrouter",
+        "wardwright",
     ];
 
     pub fn display_name(self) -> &'static str {
@@ -204,6 +210,7 @@ impl GatewayType {
             GatewayType::TensorZero => "TensorZero gateway",
             GatewayType::FutureAgi => "Future AGI gateway",
             GatewayType::OpenRouter => "OpenRouter",
+            GatewayType::Wardwright => "Wardwright synthetic model gateway",
             GatewayType::Mock => "Mock provider adapter",
         }
     }
@@ -266,6 +273,14 @@ impl GatewayType {
                 observability: false,
                 operator_ui: true,
             },
+            GatewayType::Wardwright => GatewayCapabilities {
+                openai_chat_completions: true,
+                model_listing: true,
+                tool_call_transcripts: false,
+                config_validation: false,
+                observability: true,
+                operator_ui: true,
+            },
             GatewayType::Mock => GatewayCapabilities {
                 openai_chat_completions: true,
                 model_listing: true,
@@ -337,6 +352,11 @@ impl GatewayType {
                     true,
                 ),
             ],
+            GatewayType::Wardwright => vec![ProviderObservabilityCapability::new(
+                ProviderObservabilityKind::NativeDashboard,
+                "Wardwright receipt and route dashboard",
+                false,
+            )],
             GatewayType::BuiltinHttp | GatewayType::OpenRouter | GatewayType::Mock => Vec::new(),
         }
     }
@@ -351,6 +371,7 @@ impl GatewayType {
                 | GatewayType::TensorZero
                 | GatewayType::FutureAgi
                 | GatewayType::OpenRouter
+                | GatewayType::Wardwright
         )
     }
 
@@ -464,7 +485,8 @@ pub fn create_gateway(
         | GatewayType::Portkey
         | GatewayType::TensorZero
         | GatewayType::FutureAgi
-        | GatewayType::OpenRouter => {
+        | GatewayType::OpenRouter
+        | GatewayType::Wardwright => {
             // Builtin HTTP upstream calls
             // This requires a backend to be passed in
             let backend = backend.ok_or_else(|| {
@@ -785,6 +807,7 @@ impl ProviderAdapter for MockGateway {
                 total_tokens: 0,
             },
             system_fingerprint: None,
+            extra_body: serde_json::Map::new(),
         })
     }
 

crates/calciforge/src/proxy/gateway_tests.rs

@@ -49,6 +49,10 @@ fn test_gateway_type_parsing() {
         "open-router".parse::<GatewayType>().unwrap(),
         GatewayType::OpenRouter
     );
+    assert_eq!(
+        "ward-wright".parse::<GatewayType>().unwrap(),
+        GatewayType::Wardwright
+    );
     assert_eq!("mock".parse::<GatewayType>().unwrap(), GatewayType::Mock);
     assert!("unknown".parse::<GatewayType>().is_err());
 }
@@ -62,6 +66,7 @@ fn test_gateway_type_display() {
     assert_eq!(GatewayType::TensorZero.to_string(), "tensorzero");
     assert_eq!(GatewayType::FutureAgi.to_string(), "future-agi");
     assert_eq!(GatewayType::OpenRouter.to_string(), "openrouter");
+    assert_eq!(GatewayType::Wardwright.to_string(), "wardwright");
     assert_eq!(GatewayType::Mock.to_string(), "mock");
 }
 
@@ -75,6 +80,7 @@ fn named_gateway_engines_share_openai_compatible_http_core() {
         GatewayType::TensorZero,
         GatewayType::FutureAgi,
         GatewayType::OpenRouter,
+        GatewayType::Wardwright,
     ] {
         assert!(
             gateway_type.uses_openai_compatible_http_core(),
@@ -129,6 +135,36 @@ fn helicone_policy_headers_are_overlay_not_separate_gateway_core() {
     );
 }
 
+#[test]
+fn wardwright_provider_uses_shared_http_core_with_receipt_dashboard_metadata() {
+    assert!(GatewayType::Wardwright.uses_openai_compatible_http_core());
+
+    let config = GatewayConfig {
+        backend_type: GatewayType::Wardwright,
+        ui_url: Some("http://127.0.0.1:8791/admin/runtime".to_string()),
+        ..Default::default()
+    };
+    let info = config.engine_info(GatewayType::Wardwright);
+
+    assert_eq!(info.id, "wardwright");
+    assert_eq!(info.display_name, "Wardwright synthetic model gateway");
+    assert_eq!(
+        info.ui_url.as_deref(),
+        Some("http://127.0.0.1:8791/admin/runtime")
+    );
+    assert!(info.capabilities.openai_chat_completions);
+    assert!(info.capabilities.model_listing);
+    assert!(
+        !info.capabilities.config_validation,
+        "Calciforge does not call a Wardwright validation API yet"
+    );
+    assert!(
+        info.observability
+            .iter()
+            .any(|capability| capability.display_name.contains("receipt"))
+    );
+}
+
 #[test]
 fn test_mock_gateway() {
     let config = GatewayConfig {
@@ -325,6 +361,7 @@ async fn builtin_http_gateway_forwards_complete_chat_request_options() {
             total_tokens: 2,
         },
         system_fingerprint: None,
+        extra_body: serde_json::Map::new(),
     };
     let mock = server
         .mock("POST", "/v1/chat/completions")
@@ -413,6 +450,7 @@ async fn configured_authorization_header_cannot_override_backend_api_key() {
             total_tokens: 2,
         },
         system_fingerprint: None,
+        extra_body: serde_json::Map::new(),
     };
     let mock = server
         .mock("POST", "/v1/chat/completions")
@@ -590,6 +628,7 @@ async fn helicone_engine_uses_shared_http_core_with_engine_headers() {
             total_tokens: 2,
         },
         system_fingerprint: None,
+        extra_body: serde_json::Map::new(),
     };
     let mock = server
         .mock("POST", "/v1/chat/completions")

crates/calciforge/src/proxy/handlers.rs

@@ -345,7 +345,11 @@ async fn try_provider(
     let duration = start.elapsed();
 
     let event = match &result {
-        Ok(response) => telemetry_attempt.success(duration, response.choices.len()),
+        Ok(response) => telemetry_attempt.success_with_receipt_id(
+            duration,
+            response.choices.len(),
+            response.wardwright_receipt_id().map(str::to_string),
+        ),
         Err(error) => telemetry_attempt.failure(duration, error.failure_kind()),
     };
     state.telemetry.emit_gateway_attempt(event).await;
@@ -1197,6 +1201,7 @@ mod tests {
                     total_tokens: 2,
                 },
                 system_fingerprint: None,
+                extra_body: serde_json::Map::new(),
             })
         }