fix(builders,derive): lossless 2020-12 schema pipeline on the 2026 path

Two defects destroyed schema fidelity between tool-author types and
tools/list:

1. ToolSchema::from_schemars (turul-mcp-builders/schemars_helpers.rs)
   stripped $defs/definitions from the root while passing properties through
   VERBATIM on 2026 — every "#/$defs/X" pointer dangled. The 2026 root now
   retains $defs/definitions/$schema (where verbatim property pointers
   resolve); the 2025 typed lane keeps its inline-resolution + stripping.

2. The derive macros (param arm + output-schema arm in derive/utils.rs)
   funneled schemars-generated documents through the typed-enum converter,
   silently collapsing data-bearing unions (oneOf + const tags ->
   {"type":"object"}) and other 2020-12 compositions.

New lane-aware turul_mcp_builders::schemars_param_schema():
- 2026: inlines local $refs via the cycle-guarded resolve_local_refs()
  ($ref siblings compose via allOf) and carries the result verbatim through
  the new transparent JsonSchema::Raw variant — an untagged escape hatch on
  the 2026 typed enum (also the deserialize fallback for subschemas the
  structured variants reject). The 2026 typed enum is a framework vehicle,
  not a wire binding; the wire bindings already hold arbitrary Values.
- 2025: status-quo typed conversion (frozen wire model).

Documented limitations with rejection tests, not silent loss:
- cyclic $refs cannot be inlined into a property subschema (error names the
  cycle; restructure the type or build a root document via from_schemars,
  which keeps $defs at the root);
- non-local/network $refs are rejected (spec: MUST NOT auto-dereference).

Tests: 7 builders fidelity tests (nested-$defs inlining with enum/required
intact; tagged-union oneOf survival; composition keywords verbatim;
cycle + non-local rejection; $ref-sibling allOf; root $defs retention) and
2 real-HTTP e2e in schema_fidelity_2026.rs — a derived tool's tagged-union
param and schemars output reach tools/list undamaged with no dangling $ref,
and tools/call structuredContent satisfies the ADVERTISED outputSchema
wrapper field discovered from tools/list. Revert-and-fail: with the 2026 arm
forced through the old converter, the tagged-union test fails showing the
exact loss ("shape":{"type":"object"}) — recorded. One derive unit test
migrated with the contract (asserts the new helper call). No public
macro/builder API shape changed (stop condition not hit).

Docs: review checklist updated — pipeline items plus the seven P1 fidelity
items closed earlier today (incl. the SEP-2577 line codex flagged as report
drift). CI: schema_fidelity_2026 gate in ci.yml + ci-gates.sh.

Author: hortovanyi

.github/workflows/ci.yml

@@ -55,6 +55,8 @@ jobs:
         run: cargo test -p turul-mcp-server --no-default-features --features http,sse,protocol-2026-07-28 --test mcp_param_2026
       - name: 2026 per-request log gating (logLevel opt-in)
         run: cargo test -p turul-mcp-server --no-default-features --features http,sse,protocol-2026-07-28 --test log_gating_2026
+      - name: 2026 schema fidelity (derive/builders pipeline to the wire)
+        run: cargo test -p turul-mcp-server --no-default-features --features http,sse,protocol-2026-07-28 --test schema_fidelity_2026
       - name: protocol-2026 compliance + upstream wire fixtures
         run: cargo test -p turul-mcp-protocol-2026-07-28 --features compliance
       - name: Bilingual client (not in default-members)

CHANGELOG.md

@@ -37,6 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed (2026-06-10)
 
+- **Builders/derive schema pipeline is lossless on the 2026 path.** Two defects destroyed JSON Schema 2020-12 fidelity between a tool author's types and `tools/list`: (1) `ToolSchema::from_schemars` stripped `$defs`/`definitions` from the root while passing properties through verbatim — every `#/$defs/X` pointer dangled; the 2026 root now RETAINS `$defs`/`definitions`/`$schema` (the 2025 typed lane keeps its inline-resolution and stripping). (2) The derive macros funneled schemars-generated parameter and output schemas through the typed-enum converter, silently collapsing data-bearing unions (`oneOf` + `const` tags → bare `{"type":"object"}`) and other 2020-12 compositions. New lane-aware `turul_mcp_builders::schemars_param_schema`: on 2026 it inlines local `$ref`s (cycle-guarded `resolve_local_refs`; `$ref` siblings compose via `allOf`) and carries the result verbatim via the new transparent `JsonSchema::Raw` variant (untagged escape hatch on the 2026 typed enum — also the deserialize fallback for subschemas the structured variants reject); on 2025 it is the status-quo typed conversion. **Documented limitations with rejection tests** (not silent loss): cyclic `$ref`s cannot be inlined into a property subschema (error names the cycle; restructure the type or use a root `from_schemars` document), and non-local/network `$ref`s are rejected per the spec's no-auto-deref rule. Tests: 7 builders fidelity tests (nested `$defs` inlining with enum/required intact, tagged-union `oneOf` survival, composition-keyword verbatim round-trip, cycle/non-local rejection, `$ref`-sibling `allOf` composition, root `$defs` retention) + 2 real-HTTP e2e (`schema_fidelity_2026.rs`: a derived tool's tagged-union param and schemars output reach `tools/list` undamaged with no dangling `$ref`; `tools/call` `structuredContent` satisfies the ADVERTISED `outputSchema` wrapper field discovered from `tools/list`). Revert-and-fail: with the 2026 arm forced through the old converter, the tagged-union test fails showing the exact loss (`"shape":{"type":"object"}`) — recorded. No public macro/builder API shape changed.
 - **Protocol-fidelity sweep, part 2 — `ttlMs` as a schema `number` + SEP-2577 marker absorption.** (a) `CacheableResult.ttlMs` (and its embeddings in the tools/resources/prompts/discover results) is now `f64` per the schema's `number` type: fractional values are accepted on deserialize and survive round trips, negative/non-finite values reject (`@minimum 0`), and whole values keep the compact integer wire form (byte-stable for the common `ttlMs: 0` case). (b) The re-pinned schema's SEP-2577 deprecations are now fully absorbed as `#[deprecated]` markers: `LoggingLevel` (+ `LogLevel` alias), the per-request `_meta` `logLevel` key and `RequestMetaObject.log_level`/`with_log_level`, `ServerCapabilities.logging`, `ModelHint`/`ModelPreferences`/`ToolChoice`, the `ContentBlock::ToolUse`/`ToolResult` variants and constructors, and the sampling trait surface (`HasCreateMessageRequestParams`/`CreateMessageRequest`/`CreateMessageResult`/`HasLevelParam`). The earlier rustdoc claim that `LoggingLevel`/`logLevel` were "the non-deprecated replacement" was wrong against the re-pin and is corrected — the whole Logging surface (including the per-request opt-in this branch implements) is deprecated-but-normative through the migration window. Framework-internal use sites carry scoped `#[allow(deprecated)]` (the framework intentionally serves the surface through the window); downstream consumers now get compiler nudges.
 - **Protocol-fidelity sweep, part 1 (wire/type drift vs the pinned schema).** (a) `ToolChoice` no longer carries a non-spec `name` field on the wire (the `specific()` constructor is gone) and `mode` is optional per schema (`{}` parses; absent means `"auto"`; `effective_mode()` helper). (b) `PromptReference` is `BaseMetadata`-shaped: gains `title`, drops the non-spec `description`. (c) `Annotations.audience` is the closed `Role[]` union instead of `Vec<String>` — wire-invalid values like `"system"` are now rejected at parse time; the builders' `annotation_audience` takes `Role` (converted to strings on the frozen 2025 lane). (d) The duplicate `Role` binding is gone — `sampling::Role` re-exports the single `prompts::Role`. (e) `LoggingCapabilities`/`CompletionsCapabilities` match the schema's opaque `JSONObject`: the invented `enabled`/`levels` keys are removed from the bindings and from both server builders' capability advertisements (presence of the object is the signal). 5 new wire-shape contract tests in `compliance.rs`; existing tests migrated with the contract (e.g. the empty `ToolChoice` parse fails against the pre-fix required-`mode` binding).
 

crates/turul-mcp-builders/src/lib.rs

@@ -153,6 +153,7 @@ pub mod tool;
 pub mod schemars_helpers;
 pub use schemars_helpers::{
     ToolSchemaExt, convert_value_to_json_schema, convert_value_to_json_schema_with_defs,
+    resolve_local_refs, schemars_param_schema,
 };
 
 // Schema provider with automatic JsonSchema detection

crates/turul-mcp-builders/src/schemars_helpers.rs

@@ -397,7 +397,13 @@ impl ToolSchemaExt for ToolSchema {
                 .collect()
         });
 
-        // Preserve remaining top-level fields (description, title, additionalProperties, etc.)
+        // Preserve remaining top-level fields (description, title,
+        // additionalProperties, etc.). Lane split: the 2025 typed model
+        // resolves `$ref`s into inline schemas, so its root drops
+        // `$defs`/`definitions`/`$schema`; the 2026 path keeps properties
+        // VERBATIM, so the root must retain `$defs`/`definitions` (otherwise
+        // every `#/$defs/X` pointer dangles) and the `$schema` dialect marker.
+        #[cfg(feature = "protocol-2025-11-25")]
         let reserved = [
             "type",
             "properties",
@@ -406,6 +412,8 @@ impl ToolSchemaExt for ToolSchema {
             "definitions",
             "$schema",
         ];
+        #[cfg(feature = "protocol-2026-07-28")]
+        let reserved = ["type", "properties", "required"];
         let additional: HashMap<String, Value> = obj
             .iter()
             .filter(|(k, _)| !reserved.contains(&k.as_str()))
@@ -421,6 +429,119 @@ impl ToolSchemaExt for ToolSchema {
     }
 }
 
+/// Inline every local `$ref` (`#/$defs/X`, `#/definitions/X`) in `value`
+/// against `defs`, recursively. Errors on unresolvable pointers and on
+/// cyclic references — cyclic schemas cannot be inlined and are not
+/// supported as tool parameter/output types (restructure the type, or build
+/// the whole `ToolSchema` from a root schemars document via `from_schemars`,
+/// which keeps `$defs` at the schema root instead).
+pub fn resolve_local_refs(value: &Value, defs: &HashMap<String, Value>) -> Result<Value, String> {
+    fn walk(
+        value: &Value,
+        defs: &HashMap<String, Value>,
+        stack: &mut Vec<String>,
+    ) -> Result<Value, String> {
+        match value {
+            Value::Object(obj) => {
+                if let Some(reference) = obj.get("$ref").and_then(|r| r.as_str()) {
+                    let name = reference
+                        .strip_prefix("#/$defs/")
+                        .or_else(|| reference.strip_prefix("#/definitions/"))
+                        .ok_or_else(|| {
+                            format!("unsupported non-local $ref '{reference}' in tool schema")
+                        })?;
+                    if stack.iter().any(|n| n == name) {
+                        return Err(format!(
+                            "cyclic $ref '#/$defs/{name}' cannot be inlined into a tool                              property schema"
+                        ));
+                    }
+                    let definition = defs.get(name).ok_or_else(|| {
+                        format!("dangling $ref '{reference}': no such definition")
+                    })?;
+                    stack.push(name.to_string());
+                    let resolved = walk(definition, defs, stack)?;
+                    stack.pop();
+                    // 2020-12 allows $ref siblings; preserve them alongside the
+                    // resolved schema via allOf composition.
+                    let siblings: serde_json::Map<String, Value> = obj
+                        .iter()
+                        .filter(|(k, _)| k.as_str() != "$ref")
+                        .map(|(k, v)| Ok((k.clone(), walk(v, defs, stack)?)))
+                        .collect::<Result<_, String>>()?;
+                    if siblings.is_empty() {
+                        Ok(resolved)
+                    } else {
+                        let mut combined = siblings;
+                        combined.insert("allOf".to_string(), Value::Array(vec![resolved]));
+                        Ok(Value::Object(combined))
+                    }
+                } else {
+                    obj.iter()
+                        .map(|(k, v)| Ok((k.clone(), walk(v, defs, stack)?)))
+                        .collect::<Result<serde_json::Map<_, _>, String>>()
+                        .map(Value::Object)
+                }
+            }
+            Value::Array(items) => items
+                .iter()
+                .map(|v| walk(v, defs, &mut stack.clone()))
+                .collect::<Result<Vec<_>, String>>()
+                .map(Value::Array),
+            other => Ok(other.clone()),
+        }
+    }
+    let mut stack = Vec::new();
+    walk(value, defs, &mut stack)
+}
+
+/// Convert a schemars-generated document into a single property/field
+/// subschema for embedding inside a `ToolSchema`.
+///
+/// 2026-07-28: local `$ref`s are inlined (a subschema cannot carry the
+/// document-root `$defs` its absolute pointers need) and the result is a
+/// verbatim 2020-12 [`JsonSchema::Raw`] — `oneOf`/`anyOf`/`allOf`, `const`,
+/// enum constraints, and nested object trees survive untouched.
+/// 2025-11-25: the structured typed conversion (the wire model there is the
+/// typed enum).
+///
+/// # Panics
+/// On cyclic `$ref`s — cyclic schemas cannot be inlined into a property
+/// subschema and are not supported as tool parameter/output types. Surface a
+/// non-recursive type instead.
+pub fn schemars_param_schema(schema: schemars::Schema) -> JsonSchema {
+    let schema_value =
+        serde_json::to_value(&schema).expect("schemars schema should serialize to JSON");
+
+    let definitions: HashMap<String, Value> = ["$defs", "definitions"]
+        .iter()
+        .filter_map(|k| schema_value.get(*k).and_then(|v| v.as_object()))
+        .flat_map(|obj| obj.iter().map(|(k, v)| (k.clone(), v.clone())))
+        .collect();
+
+    #[cfg(feature = "protocol-2026-07-28")]
+    {
+        let resolved = resolve_local_refs(&schema_value, &definitions)
+            .unwrap_or_else(|e| panic!("unsupported tool schema: {e}"));
+        let mut resolved = resolved;
+        if let Some(obj) = resolved.as_object_mut() {
+            obj.remove("$schema");
+            obj.remove("$defs");
+            obj.remove("definitions");
+        }
+        JsonSchema::raw(resolved)
+    }
+
+    #[cfg(feature = "protocol-2025-11-25")]
+    {
+        let mut schema_value = schema_value;
+        if let Some(obj) = schema_value.as_object_mut() {
+            obj.remove("$defs");
+            obj.remove("definitions");
+        }
+        convert_value_to_json_schema_with_defs(&schema_value, &definitions)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -571,3 +692,193 @@ mod tests {
         );
     }
 }
+
+#[cfg(all(test, feature = "protocol-2026-07-28"))]
+mod schema_fidelity_2026_tests {
+    //! 2020-12 fidelity through the 2026 conversion pipeline: nothing a
+    //! schemars-generated document expresses may be silently downgraded.
+    use super::*;
+    use schemars::{JsonSchema as SchemarsJsonSchema, schema_for};
+    use serde::Serialize;
+    use serde_json::json;
+
+    #[derive(Serialize, SchemarsJsonSchema)]
+    #[allow(dead_code)]
+    enum Mode {
+        Fast,
+        Thorough,
+    }
+
+    #[derive(Serialize, SchemarsJsonSchema)]
+    #[allow(dead_code)]
+    struct Inner {
+        threshold: f64,
+        mode: Mode,
+    }
+
+    #[derive(Serialize, SchemarsJsonSchema)]
+    #[allow(dead_code)]
+    struct Outer {
+        name: String,
+        inner: Inner,
+        tags: Vec<Mode>,
+    }
+
+    #[test]
+    fn nested_defs_are_inlined_with_constraints_intact() {
+        let schema = schema_for!(Outer);
+        let prop = schemars_param_schema(schema);
+        let v = serde_json::to_value(&prop).unwrap();
+
+        // No dangling pointers and no orphaned defs.
+        let rendered = v.to_string();
+        assert!(
+            !rendered.contains("$ref"),
+            "local $refs must be inlined: {rendered}"
+        );
+        assert!(
+            !rendered.contains("$defs") && !rendered.contains("definitions"),
+            "defs must not leak into a property subschema: {rendered}"
+        );
+
+        // The nested object tree survives with required + enum constraints.
+        assert_eq!(v["type"], "object");
+        assert_eq!(v["properties"]["inner"]["type"], "object");
+        assert!(
+            v["properties"]["inner"]["properties"]["threshold"]["type"] == "number",
+            "nested numeric property must survive: {v}"
+        );
+        let mode = &v["properties"]["inner"]["properties"]["mode"];
+        assert!(
+            mode.to_string().contains("Fast") && mode.to_string().contains("Thorough"),
+            "enum variants must survive inlining: {v}"
+        );
+        assert!(
+            v["properties"]["tags"]["items"].is_object(),
+            "array items must survive: {v}"
+        );
+        let required: Vec<_> = v["required"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .filter_map(|r| r.as_str())
+            .collect();
+        assert!(required.contains(&"name") && required.contains(&"inner"));
+    }
+
+    #[derive(Serialize, SchemarsJsonSchema)]
+    #[serde(tag = "kind")]
+    #[allow(dead_code)]
+    enum Shape {
+        Circle { radius: f64 },
+        Rect { w: f64, h: f64 },
+    }
+
+    #[derive(Serialize, SchemarsJsonSchema)]
+    #[allow(dead_code)]
+    struct Drawing {
+        title: String,
+        shape: Shape,
+        accent: Option<Mode>,
+    }
+
+    #[test]
+    fn tagged_union_one_of_survives_the_pipeline() {
+        // A data-bearing enum renders as oneOf-with-const-tag subschemas —
+        // exactly the shape the old typed conversion DOWNGRADED (no
+        // oneOf/const in the structured model). The pipeline must carry it.
+        let schema = schema_for!(Drawing);
+        let prop = schemars_param_schema(schema);
+        let v = serde_json::to_value(&prop).unwrap();
+        let shape = v["properties"]["shape"].to_string();
+        assert!(
+            shape.contains("oneOf") || shape.contains("anyOf"),
+            "the tagged-union composition must survive: {v}"
+        );
+        assert!(
+            shape.contains("Circle") && shape.contains("Rect"),
+            "both variant tags must survive: {v}"
+        );
+        assert!(
+            shape.contains("radius"),
+            "variant payload properties must survive: {v}"
+        );
+    }
+
+    #[test]
+    fn composition_keywords_survive_verbatim() {
+        // oneOf/anyOf/allOf + const are exactly what the typed model used to
+        // downgrade; the Raw path must carry them untouched.
+        let value = json!({
+            "oneOf": [
+                {"type": "string", "const": "a"},
+                {"type": "object", "properties": {"x": {"type": "integer"}}, "required": ["x"]}
+            ],
+            "anyOf": [{"type": "string"}],
+            "allOf": [{"minProperties": 1}]
+        });
+        let resolved = resolve_local_refs(&value, &HashMap::new()).unwrap();
+        assert_eq!(
+            resolved, value,
+            "composition keywords are preserved verbatim"
+        );
+    }
+
+    #[test]
+    fn cyclic_refs_are_rejected_not_silently_lost() {
+        // A self-referential definition cannot be inlined into a property
+        // subschema — the resolver must REJECT it (documented limitation),
+        // never emit a dangling or truncated schema.
+        let defs: HashMap<String, Value> = [(
+            "Node".to_string(),
+            json!({
+                "type": "object",
+                "properties": { "next": { "$ref": "#/$defs/Node" } }
+            }),
+        )]
+        .into();
+        let value = json!({ "$ref": "#/$defs/Node" });
+        let err = resolve_local_refs(&value, &defs).unwrap_err();
+        assert!(
+            err.contains("cyclic"),
+            "cycle must be named in the error: {err}"
+        );
+    }
+
+    #[test]
+    fn non_local_refs_are_rejected() {
+        // Network/external $refs MUST NOT be auto-dereferenced (spec) — and we
+        // can't inline what we won't fetch: precise rejection.
+        let value = json!({ "$ref": "https://example.com/schema.json" });
+        let err = resolve_local_refs(&value, &HashMap::new()).unwrap_err();
+        assert!(err.contains("non-local"), "{err}");
+    }
+
+    #[test]
+    fn ref_siblings_compose_via_all_of() {
+        let defs: HashMap<String, Value> = [("S".to_string(), json!({"type": "string"}))].into();
+        let value = json!({ "$ref": "#/$defs/S", "description": "named thing" });
+        let resolved = resolve_local_refs(&value, &defs).unwrap();
+        assert_eq!(resolved["description"], "named thing");
+        assert_eq!(resolved["allOf"][0]["type"], "string");
+    }
+
+    #[test]
+    fn root_from_schemars_keeps_defs_for_verbatim_properties() {
+        // The ToolSchema root path (whole-document conversion) keeps $defs at
+        // the root, where verbatim property `#/$defs/X` pointers resolve.
+        let schema = schema_for!(Outer);
+        let tool_schema = ToolSchema::from_schemars(schema).unwrap();
+        let v = serde_json::to_value(&tool_schema).unwrap();
+        assert!(
+            v.get("$defs").is_some() || !v.to_string().contains("$ref"),
+            "either $defs ride at the root or no refs remain: {v}"
+        );
+        if let Some(defs) = v.get("$defs") {
+            assert!(
+                defs.get("Inner").is_some(),
+                "Inner definition retained: {v}"
+            );
+        }
+    }
+}

crates/turul-mcp-derive/src/tests/comprehensive_tests.rs

@@ -252,8 +252,8 @@ mod schema_generation_tests {
             "Unknown types should use schemars for schema generation, got: {schema_str}"
         );
         assert!(
-            contains_pattern(&schema_str, "convert_value_to_json_schema_with_defs"),
-            "Should use the schemars-to-JsonSchema converter, got: {schema_str}"
+            contains_pattern(&schema_str, "schemars_param_schema"),
+            "Should use the lane-aware schemars conversion helper, got: {schema_str}"
         );
     }