fix(protocol): fidelity sweep 2 — ttlMs as schema number; absorb SEP-2577 deprecation markers

(a) ttlMs: the schema declares `number` (@Minimum 0); the u64 binding
rejected spec-legal fractional values on deserialize. CacheableResult.ttl_ms
and its embeddings (ListToolsResult, ListResourcesResult,
ListResourceTemplatesResult, ReadResourceResult, ListPromptsResult,
DiscoverResult) are now f64 via a shared serde helper: fractional values
accepted and round-tripped, negative/non-finite rejected, whole values keep
the compact integer wire form (byte-stable for the common ttlMs: 0).
Contract test covers all four behaviors.

(b) SEP-2577 markers: the 2026-06-07 re-pin deprecated the WHOLE Logging
surface — including the per-request _meta logLevel opt-in and the
LoggingLevel enum — and the bindings/rustdoc still claimed those were "the
non-deprecated replacement". Corrected: #[deprecated] now on LoggingLevel
(+ LogLevel alias), META_KEY_LOG_LEVEL, RequestMetaObject.log_level /
with_log_level, ServerCapabilities.logging, ModelHint / ModelPreferences /
ToolChoice, ContentBlock::ToolUse / ToolResult (variants + constructors),
and the sampling/logging trait surface. The behavior remains normative and
implemented through the migration window (earliest removal 2027-07-28);
framework-internal call sites carry scoped #[allow(deprecated)], so the
markers reach downstream consumers without making the framework warn on
itself. Zero warnings on the default build, test build, clippy, and the
2025 opt-in lane builds.

Author: hortovanyi

CHANGELOG.md

@@ -37,6 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed (2026-06-10)
 
+- **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).
 
 - **2025 opt-in lane build regression (same day, pre-push).** The elicitation enum-union slice used the 2026-only union accessors in `turul-mcp-builders` code that also compiles under `protocol-2025-11-25`, breaking the opt-in lane builds (caught by `scripts/ci-gates.sh all`). The validation is now `#[cfg]`-split per lane.

crates/turul-mcp-aws-lambda/src/builder.rs

@@ -647,7 +647,10 @@ impl LambdaMcpServerBuilder {
     #[cfg(feature = "protocol-2025-11-25")]
     pub fn with_logging(mut self) -> Self {
         use turul_mcp_protocol::initialize::LoggingCapabilities;
-        self.capabilities.logging = Some(LoggingCapabilities::default());
+        #[allow(deprecated)] // SEP-2577 migration window
+        {
+            self.capabilities.logging = Some(LoggingCapabilities::default());
+        }
         self.handler(LoggingHandler)
     }
 
@@ -1069,7 +1072,11 @@ impl LambdaMcpServerBuilder {
 
         // Logging capability: presence of the (opaque) object means the server
         // can send notifications/message (same as McpServer).
-        capabilities.logging = Some(turul_mcp_protocol::initialize::LoggingCapabilities::default());
+        #[allow(deprecated)] // SEP-2577 migration window
+        {
+            capabilities.logging =
+                Some(turul_mcp_protocol::initialize::LoggingCapabilities::default());
+        }
 
         // Tasks capabilities — auto-configure when task runtime is set
         #[cfg(feature = "protocol-2025-11-25")]

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

@@ -8,6 +8,7 @@ use std::collections::HashMap;
 
 // Import protocol types
 use turul_mcp_json_rpc_server::types::RequestId;
+#[allow(deprecated)] // SEP-2577 migration window
 use turul_mcp_protocol::logging::LoggingLevel;
 // `LoggingMessageNotification` is deprecated-but-present in 2026-07-28 (SEP-2577); logging
 // remains a valid feature the framework supports.

crates/turul-mcp-builders/src/traits/logging_traits.rs

@@ -2,6 +2,10 @@
 //!
 //! **IMPORTANT**: These are framework features, NOT part of the MCP specification.
 
+// The Logging surface is SEP-2577-deprecated; these traits carry it
+// through the migration window.
+#![allow(deprecated)]
+
 use serde_json::Value;
 use turul_mcp_protocol::logging::LoggingLevel;
 

crates/turul-mcp-protocol-2026-07-28/src/caching.rs

@@ -66,16 +66,19 @@ pub struct CacheableResult {
     /// - `0` means immediately stale; client MAY re-fetch every use.
     /// - Positive: client SHOULD consider the result fresh for this many ms.
     ///
-    /// Schema annotation: `@minimum 0`.
-    pub ttl_ms: u64,
+    /// Schema type is `number` (`@minimum 0`) — fractional values are
+    /// spec-legal and accepted on deserialize; whole values serialize as
+    /// integers so the common case keeps its compact wire form.
+    #[serde(with = "ttl_ms_serde")]
+    pub ttl_ms: f64,
 
     /// Sharing scope.
     pub cache_scope: CacheScope,
 }
 
 impl CacheableResult {
     /// Construct with both required fields.
-    pub fn new(ttl_ms: u64, cache_scope: CacheScope) -> Self {
+    pub fn new(ttl_ms: f64, cache_scope: CacheScope) -> Self {
         Self {
             ttl_ms,
             cache_scope,
@@ -84,12 +87,38 @@ impl CacheableResult {
 
     /// Convenience: immediately-stale public response (`ttlMs=0`, public scope).
     pub fn stale_public() -> Self {
-        Self::new(0, CacheScope::Public)
+        Self::new(0.0, CacheScope::Public)
     }
 
     /// Convenience: 60-second private cache.
     pub fn private_60s() -> Self {
-        Self::new(60_000, CacheScope::Private)
+        Self::new(60_000.0, CacheScope::Private)
+    }
+}
+
+/// Serde for `ttlMs`: the schema declares `number` with `@minimum 0`.
+/// Deserialize accepts any non-negative finite number; serialize emits an
+/// integer for whole values (compact, byte-stable for the common case) and a
+/// float otherwise.
+pub mod ttl_ms_serde {
+    use serde::{Deserialize, Deserializer, Serializer};
+
+    pub fn serialize<S: Serializer>(value: &f64, serializer: S) -> Result<S::Ok, S::Error> {
+        if value.fract() == 0.0 && *value >= 0.0 && *value <= (1u64 << 53) as f64 {
+            serializer.serialize_u64(*value as u64)
+        } else {
+            serializer.serialize_f64(*value)
+        }
+    }
+
+    pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<f64, D::Error> {
+        let value = f64::deserialize(deserializer)?;
+        if !value.is_finite() || value < 0.0 {
+            return Err(serde::de::Error::custom(
+                "ttlMs must be a non-negative finite number",
+            ));
+        }
+        Ok(value)
     }
 }
 
@@ -122,7 +151,7 @@ mod tests {
     #[test]
     fn cacheable_result_serializes_required_fields() {
         // Both fields REQUIRED on the wire.
-        let c = CacheableResult::new(5000, CacheScope::Public);
+        let c = CacheableResult::new(5000.0, CacheScope::Public);
         let v = serde_json::to_value(&c).unwrap();
         assert_eq!(v["ttlMs"], 5000);
         assert_eq!(v["cacheScope"], "public");
@@ -152,17 +181,17 @@ mod tests {
     #[test]
     fn cacheable_result_accepts_zero_ttl() {
         // Schema: "If 0, the response SHOULD be considered immediately stale".
-        let c = CacheableResult::new(0, CacheScope::Public);
+        let c = CacheableResult::new(0.0, CacheScope::Public);
         let v = serde_json::to_value(&c).unwrap();
         assert_eq!(v["ttlMs"], 0);
     }
 
     #[test]
     fn cacheable_result_round_trips() {
-        let c = CacheableResult::new(86_400_000, CacheScope::Private);
+        let c = CacheableResult::new(86_400_000.0, CacheScope::Private);
         let s = serde_json::to_string(&c).unwrap();
         let parsed: CacheableResult = serde_json::from_str(&s).unwrap();
-        assert_eq!(parsed.ttl_ms, 86_400_000);
+        assert_eq!(parsed.ttl_ms, 86_400_000.0);
         assert_eq!(parsed.cache_scope, CacheScope::Private);
     }
 
@@ -180,7 +209,7 @@ mod tests {
 
         let l = ListLike {
             tools: vec!["echo".to_string()],
-            cache: CacheableResult::new(60_000, CacheScope::Public),
+            cache: CacheableResult::new(60_000.0, CacheScope::Public),
         };
         let v = serde_json::to_value(&l).unwrap();
         assert_eq!(v["tools"][0], "echo");
@@ -192,18 +221,18 @@ mod tests {
 
         let s = serde_json::to_string(&v).unwrap();
         let parsed: ListLike = serde_json::from_str(&s).unwrap();
-        assert_eq!(parsed.cache.ttl_ms, 60_000);
+        assert_eq!(parsed.cache.ttl_ms, 60_000.0);
         assert_eq!(parsed.cache.cache_scope, CacheScope::Public);
     }
 
     #[test]
     fn helpers_produce_expected_values() {
         let stale = CacheableResult::stale_public();
-        assert_eq!(stale.ttl_ms, 0);
+        assert_eq!(stale.ttl_ms, 0.0);
         assert_eq!(stale.cache_scope, CacheScope::Public);
 
         let p60 = CacheableResult::private_60s();
-        assert_eq!(p60.ttl_ms, 60_000);
+        assert_eq!(p60.ttl_ms, 60_000.0);
         assert_eq!(p60.cache_scope, CacheScope::Private);
     }
 }

crates/turul-mcp-protocol-2026-07-28/src/content.rs

@@ -152,6 +152,11 @@ pub enum ContentBlock {
         meta: Option<HashMap<String, Value>>,
     },
     /// Tool use content block.
+    #[deprecated(
+        since = "0.4.0",
+        note = "Deprecated per SEP-2577 (DRAFT-2026-v1) with the Sampling surface. \
+                Earliest removal: first release on/after 2027-07-28."
+    )]
     #[serde(rename = "tool_use")]
     ToolUse {
         /// Unique identifier for this tool use
@@ -164,6 +169,11 @@ pub enum ContentBlock {
         meta: Option<HashMap<String, Value>>,
     },
     /// Tool result content block.
+    #[deprecated(
+        since = "0.4.0",
+        note = "Deprecated per SEP-2577 (DRAFT-2026-v1) with the Sampling surface. \
+                Earliest removal: first release on/after 2027-07-28."
+    )]
     #[serde(rename = "tool_result")]
     ToolResult {
         /// ID of the tool use this result corresponds to
@@ -240,6 +250,11 @@ impl ContentBlock {
     }
 
     /// Create tool use content block
+    #[allow(deprecated)]
+    #[deprecated(
+        since = "0.4.0",
+        note = "Deprecated per SEP-2577 (DRAFT-2026-v1) with the Sampling surface."
+    )]
     pub fn tool_use(
         id: impl Into<String>,
         name: impl Into<String>,
@@ -254,6 +269,11 @@ impl ContentBlock {
     }
 
     /// Create tool result content block
+    #[allow(deprecated)]
+    #[deprecated(
+        since = "0.4.0",
+        note = "Deprecated per SEP-2577 (DRAFT-2026-v1) with the Sampling surface."
+    )]
     pub fn tool_result(tool_use_id: impl Into<String>, content: Vec<ContentBlock>) -> Self {
         Self::ToolResult {
             tool_use_id: tool_use_id.into(),
@@ -265,6 +285,11 @@ impl ContentBlock {
     }
 
     /// Create tool result error content block
+    #[allow(deprecated)]
+    #[deprecated(
+        since = "0.4.0",
+        note = "Deprecated per SEP-2577 (DRAFT-2026-v1) with the Sampling surface."
+    )]
     pub fn tool_result_error(tool_use_id: impl Into<String>, content: Vec<ContentBlock>) -> Self {
         Self::ToolResult {
             tool_use_id: tool_use_id.into(),
@@ -277,6 +302,7 @@ impl ContentBlock {
 
     /// Add annotations to any content block that supports them.
     /// ToolUse and ToolResult do not have annotations per spec — this is a no-op for those variants.
+    #[allow(deprecated)] // matches the SEP-2577-deprecated variants
     pub fn with_annotations(mut self, annotations: Annotations) -> Self {
         match &mut self {
             ContentBlock::Text { annotations: a, .. }
@@ -293,6 +319,7 @@ impl ContentBlock {
     }
 
     /// Add meta to any content block
+    #[allow(deprecated)] // matches the SEP-2577-deprecated variants
     pub fn with_meta(mut self, meta: HashMap<String, Value>) -> Self {
         match &mut self {
             ContentBlock::Text { meta: m, .. }
@@ -455,6 +482,7 @@ impl BlobResourceContents {
 }
 
 #[cfg(test)]
+#[allow(deprecated)] // exercises SEP-2577-deprecated surfaces
 mod tests {
     use super::*;
     use serde_json::json;

crates/turul-mcp-protocol-2026-07-28/src/discover.rs

@@ -70,7 +70,8 @@ pub struct DiscoverResult {
     pub result_type: ResultType,
 
     /// `CacheableResult.ttlMs` — required by schema (DiscoverResult extends CacheableResult).
-    pub ttl_ms: u64,
+    #[serde(with = "crate::caching::ttl_ms_serde")]
+    pub ttl_ms: f64,
     /// `CacheableResult.cacheScope` — required by schema.
     pub cache_scope: crate::caching::CacheScope,
 
@@ -105,7 +106,7 @@ impl DiscoverResult {
     ) -> Self {
         Self {
             result_type: ResultType::Complete,
-            ttl_ms: 0,
+            ttl_ms: 0.0,
             cache_scope: crate::caching::CacheScope::Public,
             supported_versions,
             capabilities,
@@ -116,7 +117,7 @@ impl DiscoverResult {
     }
 
     /// Set the cache-control hint (`ttlMs` + `cacheScope`).
-    pub fn with_cache(mut self, ttl_ms: u64, cache_scope: crate::caching::CacheScope) -> Self {
+    pub fn with_cache(mut self, ttl_ms: f64, cache_scope: crate::caching::CacheScope) -> Self {
         self.ttl_ms = ttl_ms;
         self.cache_scope = cache_scope;
         self

crates/turul-mcp-protocol-2026-07-28/src/initialize.rs

@@ -251,6 +251,11 @@ pub struct CompletionsCapabilities {
 pub struct ServerCapabilities {
     /// Logging capabilities.
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[deprecated(
+        since = "0.4.0",
+        note = "Deprecated per SEP-2577 (DRAFT-2026-v1) — the Logging capability is being \
+                phased out. Earliest removal: first release on/after 2027-07-28."
+    )]
     pub logging: Option<LoggingCapabilities>,
     /// Completion capabilities.
     #[serde(skip_serializing_if = "Option::is_none")]

crates/turul-mcp-protocol-2026-07-28/src/lib.rs

@@ -160,6 +160,7 @@ pub use input_required::{
 };
 pub use json_rpc::{JSONRPC_VERSION, PaginatedRequestParams, RequestParams};
 pub use meta::{Cursor as MetaCursor, ProgressToken};
+#[allow(deprecated)] // META_KEY_LOG_LEVEL re-exported through the SEP-2577 migration window
 pub use meta::{
     META_KEY_BAGGAGE, META_KEY_CLIENT_CAPABILITIES, META_KEY_CLIENT_INFO, META_KEY_LOG_LEVEL,
     META_KEY_PROTOCOL_VERSION, META_KEY_SUBSCRIPTION_ID, META_KEY_TRACEPARENT, META_KEY_TRACESTATE,

crates/turul-mcp-protocol-2026-07-28/src/logging.rs

@@ -18,18 +18,22 @@
 //! The wire-payload types ([`crate::notifications::LoggingMessageNotification`]
 //! and [`crate::notifications::LoggingMessageNotificationParams`]) live in
 //! [`crate::notifications`] alongside the other notification payloads. This
-//! module carries only the wire-value enum [`LoggingLevel`] (still used by
-//! the non-deprecated [`crate::meta::RequestMetaObject::log_level`] field).
+//! module carries only the wire-value enum [`LoggingLevel`], used by the
+//! per-request [`crate::meta::RequestMetaObject::log_level`] opt-in — the
+//! whole Logging surface, including that opt-in and this enum, is deprecated
+//! per SEP-2577 and remains functional through the migration window.
 
 use serde::{Deserialize, Serialize};
 
 /// Logging levels (per MCP spec)
 /// Maps to syslog message severities as specified in RFC-5424.
-///
-/// NOT deprecated: this enum is the wire-value type for both the deprecated
-/// `notifications/message` surface AND the non-deprecated per-request
-/// `_meta.io.modelcontextprotocol/logLevel` opt-in. Deprecating it would
-/// cascade a warning into the replacement mechanism.
+#[deprecated(
+    since = "0.4.0",
+    note = "Deprecated per SEP-2577 (DRAFT-2026-v1) along with the whole Logging surface, \
+            including the per-request _meta logLevel opt-in this enum values. \
+            Replacement: stderr (stdio) or OpenTelemetry. \
+            Earliest removal: first release on/after 2027-07-28."
+)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum LoggingLevel {
@@ -44,9 +48,15 @@ pub enum LoggingLevel {
 }
 
 /// Type alias for compatibility (per MCP spec)
+#[allow(deprecated)]
+#[deprecated(
+    since = "0.4.0",
+    note = "Deprecated per SEP-2577 (DRAFT-2026-v1) — see LoggingLevel."
+)]
 pub type LogLevel = LoggingLevel;
 
 /// Convenience constructors for LoggingLevel
+#[allow(deprecated)]
 impl LoggingLevel {
     /// Get logging level priority (0 = debug, 7 = emergency)
     pub fn priority(&self) -> u8 {
@@ -69,6 +79,7 @@ impl LoggingLevel {
 }
 
 #[cfg(test)]
+#[allow(deprecated)] // exercises SEP-2577-deprecated surfaces
 mod tests {
     use super::*;