Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix: PR-E2 recursive JSON Schema key sort (Phase E)
chopratejas9112fed9379c
diff --git a/crates/headroom-proxy/src/cache_stabilization/mod.rs b/crates/headroom-proxy/src/cache_stabilization/mod.rsindex 99994a794..7ae753d4c 100644--- a/crates/headroom-proxy/src/cache_stabilization/mod.rs+++ b/crates/headroom-proxy/src/cache_stabilization/mod.rs@@ -28,9 +28,13 @@//! `cache_drift_observed` when consecutive requests on the same//! session disagree on any of the three dimensions.//! - [`tool_def_normalize`] — PR-E1 / PR-E2: sorts `tools[]`-//! alphabetically by name; recursively sorts JSON Schema object-//! keys inside each tool's `input_schema`. PAYG-only; skipped when-//! any tool already carries `cache_control`.+//! alphabetically by name (PR-E1) and recursively sorts JSON+//! Schema object keys inside each tool's `input_schema` /+//! `function.parameters` (PR-E2). PAYG-only. PR-E1 additionally+//! skips when any tool already carries a top-level+//! `cache_control` marker; PR-E2 has no marker check because+//! sorting schema keys never moves the marker (which lives on+//! the tool object, not inside the schema).//! - [`anthropic_cache_control`] — PR-E3: on PAYG-classified//! requests where the customer hasn't placed any `cache_control`//! marker, auto-inserts one ephemeral marker on the last tooldiff --git a/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs b/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rsindex fb3ac0031..aaa5557b2 100644--- a/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs+++ b/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs@@ -58,17 +58,22 @@ use serde_json::Value;////// # Stability///-/// Uses `Vec::sort_by` (a stable sort: equal keys preserve original-/// order). Two unnamed tools that happen to MD5-collide will keep their+/// Uses a stable sort (`sort_by_key`): equal keys preserve original+/// order. Two unnamed tools that happen to MD5-collide will keep their/// original relative order — collision is astronomically rare for any/// realistic input but the contract still holds.-pub fn sort_tools_deterministically(tools: &mut Vec<Value>) -> bool {+///+/// The slice signature (`&mut [Value]`) is preferred over `&mut+/// Vec<Value>` per clippy's `ptr_arg` guidance: callers can pass+/// either a `Vec` or any `&mut [Value]`, and we don't need+/// `Vec`-specific operations.+pub fn sort_tools_deterministically(tools: &mut [Value]) -> bool {// Capture the pre-sort key sequence so the return-value contract// (`true` iff anything moved) is exact. We compare keys, not full// values, because the sort is by key — equal-key swaps would not// affect cache bytes.let before: Vec<String> = tools.iter().map(sort_key).collect();- tools.sort_by(|a, b| sort_key(a).cmp(&sort_key(b)));+ tools.sort_by_key(sort_key);let after: Vec<String> = tools.iter().map(sort_key).collect();before != after}@@ -131,9 +136,80 @@ fn sort_key(tool: &Value) -> String {/// caught — but they would also not be position-dependent, so the/// safety contract still holds.pub fn any_tool_has_cache_control(tools: &[Value]) -> bool {- tools- .iter()- .any(|tool| tool.get("cache_control").is_some())+ tools.iter().any(|tool| tool.get("cache_control").is_some())+}++/// Recursively sort the keys of every JSON object node in `value`,+/// in place. PR-E2.+///+/// JSON Schema permits arbitrary key order, but cache hits require+/// byte-identical bytes. Different SDK serializers emit keys in+/// different orders (some sort, some preserve insertion, some are+/// hash-randomized). This walker rewrites every `Value::Object` with+/// keys in alphabetic order so the same logical schema serializes+/// to the same bytes regardless of upstream serializer behaviour.+///+/// # Array semantics+///+/// JSON Schema arrays are ordered. `oneOf`, `anyOf`, `allOf`,+/// `prefixItems`, and `enum` all carry semantic meaning in the+/// element order — so this walker recurses into arrays element by+/// element but does NOT reorder the arrays themselves. (Reordering+/// `oneOf` would be a no-op semantically but would still change+/// bytes; we preserve customer order to honour intent.)+///+/// # Idempotency+///+/// Sorting an already-sorted map yields byte-identical output: we+/// rebuild a fresh `serde_json::Map` populated in alphabetic order,+/// and `Map` (with the workspace `preserve_order` feature) emits+/// keys in insertion order. So the second pass produces the same+/// `Map` literal.+///+/// # Marker safety+///+/// Unlike PR-E1, this function has no `cache_control`-marker check.+/// The Anthropic API places `cache_control` on the tool *object* itself+/// (`{"name": ..., "cache_control": {...}, "input_schema": {...}}`),+/// not inside `input_schema`. Sorting keys inside `input_schema` does+/// not move the marker, so the customer's cache-breakpoint intent is+/// preserved either way. The caller is therefore free to pass a+/// schema for any tool, marker-bearing or not.+pub fn sort_schema_keys_recursive(value: &mut Value) {+ match value {+ Value::Object(map) => {+ // Recurse first so children are normalized before we+ // rebuild the parent. Order of recursion doesn't affect+ // correctness (each child is independent) but doing it+ // first means the parent's sorted Map is built once over+ // already-sorted children — no repeated work.+ for (_k, v) in map.iter_mut() {+ sort_schema_keys_recursive(v);+ }+ // Collect existing entries, sort by key, rebuild the+ // map. Cloning is unavoidable: `serde_json::Map` does+ // not expose an in-place key reorder. The clone is a+ // shallow Value clone — children were already mutated+ // in place above so we don't lose the recursive sort.+ let mut entries: Vec<(String, Value)> =+ map.iter().map(|(k, v)| (k.clone(), v.clone())).collect();+ entries.sort_by(|a, b| a.0.cmp(&b.0));+ map.clear();+ for (k, v) in entries {+ map.insert(k, v);+ }+ }+ Value::Array(items) => {+ // Preserve array order — JSON Schema arrays are ordered.+ // Recurse into each element so nested objects inside the+ // array still get key-sorted.+ for item in items.iter_mut() {+ sort_schema_keys_recursive(item);+ }+ }+ // Strings, numbers, booleans, null have no keys to sort.+ _ => {}+ }}#[cfg(test)]@@ -294,4 +370,145 @@ mod tests {prop_assert_eq!(tools.len(), len_before);}}++ // ─── E2: sort_schema_keys_recursive ───────────────────────────++ #[test]+ fn sorts_top_level_object_keys() {+ let mut value = json!({+ "type": "object",+ "properties": {},+ "required": [],+ });+ sort_schema_keys_recursive(&mut value);+ let serialized = serde_json::to_string(&value).unwrap();+ let p_pos = serialized.find("\"properties\"").unwrap();+ let r_pos = serialized.find("\"required\"").unwrap();+ let t_pos = serialized.find("\"type\"").unwrap();+ assert!(+ p_pos < r_pos && r_pos < t_pos,+ "expected alphabetic order properties < required < type, got: {serialized}"+ );+ }++ #[test]+ fn sorts_nested_property_keys() {+ let mut value = json!({+ "type": "object",+ "properties": {+ "z_field": {"type": "string"},+ "a_field": {"type": "integer"},+ "m_field": {"type": "boolean"},+ },+ });+ sort_schema_keys_recursive(&mut value);+ let serialized = serde_json::to_string(&value).unwrap();+ let a_pos = serialized.find("\"a_field\"").unwrap();+ let m_pos = serialized.find("\"m_field\"").unwrap();+ let z_pos = serialized.find("\"z_field\"").unwrap();+ assert!(+ a_pos < m_pos && m_pos < z_pos,+ "nested property keys must be sorted alphabetically; got: {serialized}"+ );+ }++ #[test]+ fn preserves_array_order_in_oneof() {+ let mut value = json!({+ "oneOf": [+ {"const": "third"},+ {"const": "first"},+ {"const": "second"},+ ],+ });+ sort_schema_keys_recursive(&mut value);+ let arr = value.get("oneOf").and_then(Value::as_array).unwrap();+ let consts: Vec<&str> = arr+ .iter()+ .map(|v| v.get("const").and_then(Value::as_str).unwrap())+ .collect();+ assert_eq!(+ consts,+ vec!["third", "first", "second"],+ "JSON Schema arrays (oneOf) must preserve element order"+ );+ }++ #[test]+ fn idempotent_resort_schema() {+ let mut value = json!({+ "type": "object",+ "properties": {+ "z": {"type": "integer", "default": 1, "description": "z field"},+ "a": {"type": "string", "minLength": 1, "default": "x"},+ },+ "additionalProperties": false,+ "required": ["a", "z"],+ });+ sort_schema_keys_recursive(&mut value);+ let bytes_first = serde_json::to_vec(&value).unwrap();+ sort_schema_keys_recursive(&mut value);+ let bytes_second = serde_json::to_vec(&value).unwrap();+ assert_eq!(+ bytes_first, bytes_second,+ "second sort over already-sorted schema must be a byte-equal no-op"+ );+ }++ #[test]+ fn does_not_alter_arrays_within_arrays() {+ // Nested arrays preserve order at every level.+ let mut value = json!({+ "examples": [+ [3, 1, 2],+ ["c", "a", "b"],+ ],+ });+ sort_schema_keys_recursive(&mut value);+ let outer = value.get("examples").and_then(Value::as_array).unwrap();+ let inner_nums: Vec<i64> = outer[0]+ .as_array()+ .unwrap()+ .iter()+ .map(|v| v.as_i64().unwrap())+ .collect();+ assert_eq!(inner_nums, vec![3, 1, 2]);+ let inner_strs: Vec<&str> = outer[1]+ .as_array()+ .unwrap()+ .iter()+ .map(|v| v.as_str().unwrap())+ .collect();+ assert_eq!(inner_strs, vec!["c", "a", "b"]);+ }++ #[test]+ fn handles_deeply_nested_schemas() {+ let mut value = json!({+ "type": "object",+ "properties": {+ "outer": {+ "type": "object",+ "properties": {+ "inner": {+ "type": "object",+ "properties": {+ "z_deep": {"type": "string"},+ "a_deep": {"type": "integer"},+ },+ "required": ["z_deep", "a_deep"],+ },+ },+ },+ },+ });+ sort_schema_keys_recursive(&mut value);+ let serialized = serde_json::to_string(&value).unwrap();+ let a_pos = serialized.find("\"a_deep\"").unwrap();+ let z_pos = serialized.find("\"z_deep\"").unwrap();+ assert!(+ a_pos < z_pos,+ "deeply-nested keys must be sorted alphabetically; got: {serialized}"+ );+ }}diff --git a/crates/headroom-proxy/src/compression/live_zone_anthropic.rs b/crates/headroom-proxy/src/compression/live_zone_anthropic.rsindex 5bfe76b14..1ae587cba 100644--- a/crates/headroom-proxy/src/compression/live_zone_anthropic.rs+++ b/crates/headroom-proxy/src/compression/live_zone_anthropic.rs@@ -51,7 +51,7 @@ use crate::cache_stabilization::anthropic_cache_control::{auto_place_anthropic_cache_control, AutoPlaceOutcome, SkipReason,};use crate::cache_stabilization::tool_def_normalize::{- any_tool_has_cache_control, sort_tools_deterministically,+ any_tool_has_cache_control, sort_schema_keys_recursive, sort_tools_deterministically,};use crate::compression::resolve_frozen_count;use crate::config::{CacheControlAutoFrozen, CompressionMode};@@ -178,14 +178,20 @@ pub fn compress_anthropic_request(//// 1. PR-E1 — sort `tools[]` alphabetically by name.// Skipped if any tool carries a `cache_control` marker.- // 2. PR-E3 — auto-place a `cache_control` marker on the+ // 2. PR-E2 — recursively sort JSON Schema object keys inside+ // every tool's `input_schema`. No marker check (markers+ // live on the tool object, not inside the schema, so+ // sorting schema keys never moves the marker).+ // 3. PR-E3 — auto-place a `cache_control` marker on the// (now-sorted) last tool. Skipped if any marker is already// present anywhere in the body.//// Why this order: E1 must run before E3 so E3 places its marker// on the deterministic "last tool after sort". If E3 ran first,// E1 would correctly skip on `marker_present` but the marker- // would be on a non-deterministic tool.+ // would be on a non-deterministic tool. E2 sits between E1 and+ // E3 because schema key order doesn't interact with marker+ // placement at all.//// OAuth and Subscription auth modes pass through byte-equal —// mutating their bytes can look like cache-evasion to the@@ -195,9 +201,9 @@ pub fn compress_anthropic_request(// dashboards can see how often each policy fires in production.// Each apply emits `eN_applied` with diagnostic fields.- // PR-E1: sort tools[] in-place on the parsed value.- let normalization_applied =- normalize_tool_definitions(&mut parsed, auth_mode, request_id);+ // PR-E1 + PR-E2: sort tools[] and schema keys in-place on the+ // parsed value.+ let normalization_applied = normalize_tool_definitions(&mut parsed, auth_mode, request_id);// PR-E3: auto-place anthropic cache_control on the last tool.let mut e3_locations: Vec<String> = Vec::new();@@ -489,19 +495,15 @@ pub fn compress_anthropic_request(/// dispatch body. Each `bool` is `true` only when the gate cleared AND/// the operation produced a byte-different result. Used by the caller/// to attribute strategies on the `Outcome::Compressed` payload.-///-/// Currently carries a single field for PR-E1; PR-E2 lands in the-/// follow-up commit and adds `e2_schema_sort` here. Keeping the flag-/// set in a struct (rather than a bare `bool`) means the second commit-/// is a pure addition.#[derive(Debug, Clone, Copy, Default)]pub(super) struct NormalizationApplied {pub e1_tool_sort: bool,+ pub e2_schema_sort: bool,}impl NormalizationApplied {pub(super) fn any(self) -> bool {- self.e1_tool_sort+ self.e1_tool_sort || self.e2_schema_sort}pub(super) fn strategies(self) -> Vec<&'static str> {@@ -509,17 +511,24 @@ impl NormalizationApplied {if self.e1_tool_sort {out.push("tool_array_sort");}+ if self.e2_schema_sort {+ out.push("schema_key_sort");+ }out}}-/// Apply PR-E1 (tool-array sort) in-place on the parsed body when-/// the auth-mode + marker gates clear.+/// Apply PR-E1 (tool-array sort) and PR-E2 (schema-key sort) in-place+/// on the parsed body when the auth-mode + marker gates clear.////// The caller owns re-serialization (because PR-E3 may also mutate/// the same parsed value before bytes are produced). Returns a flag/// set indicating which Phase E normalization step actually ran.///+/// PR-E1 (sort) is additionally skipped when any tool already carries+/// a `cache_control` marker; PR-E2 still runs in that case because+/// sorting schema keys never moves the marker.+////// Every gate skip emits a structured `tracing::info!` event so/// dashboards can see how often each policy fires in production.pub(super) fn normalize_tool_definitions(@@ -527,10 +536,10 @@ pub(super) fn normalize_tool_definitions(auth_mode: RequestAuthMode,request_id: &str,) -> NormalizationApplied {- // Auth-mode gate first — PR-E1 mutates request bytes, which is- // only safe under PAYG. OAuth and Subscription clients pass- // through byte-equal so the proxy never looks like a cache-- // evasion intermediary to the upstream.+ // Auth-mode gate first — both PR-E1 and PR-E2 mutate request+ // bytes, which is only safe under PAYG. OAuth and Subscription+ // clients pass through byte-equal so the proxy never looks+ // like a cache-evasion intermediary to the upstream.if !matches!(auth_mode, RequestAuthMode::Payg) {tracing::info!(event = "e1_skipped",@@ -540,6 +549,14 @@ pub(super) fn normalize_tool_definitions(auth_mode = auth_mode.as_str(),"tool-array sort skipped: non-PAYG auth mode passes through byte-equal");+ tracing::info!(+ event = "e2_skipped",+ request_id = %request_id,+ path = "/v1/messages",+ reason = "auth_mode",+ auth_mode = auth_mode.as_str(),+ "schema-key sort skipped: non-PAYG auth mode passes through byte-equal"+ );return NormalizationApplied::default();}@@ -556,8 +573,11 @@ pub(super) fn normalize_tool_definitions(// PR-E1 marker check. Reordering tools when any tool already// carries `cache_control` shifts what's "before" the marker and- // silently changes cache scope. Skip the sort and pass through.- if any_tool_has_cache_control(tools_in) {+ // silently changes cache scope. Skip the SORT (E1); E2 still+ // runs because sorting schema keys does not move the marker+ // (which lives on the tool object itself, not inside the schema).+ let marker_present = any_tool_has_cache_control(tools_in);+ if marker_present {tracing::info!(event = "e1_skipped",request_id = %request_id,@@ -567,7 +587,6 @@ pub(super) fn normalize_tool_definitions("tool-array sort skipped: customer cache_control marker present \on at least one tool; preserving customer-intentional order");- return NormalizationApplied::default();}let tools = parsed@@ -576,14 +595,45 @@ pub(super) fn normalize_tool_definitions(.expect("tools array verified above");let mut applied = NormalizationApplied::default();- applied.e1_tool_sort = sort_tools_deterministically(tools);- if applied.e1_tool_sort {++ if !marker_present {+ applied.e1_tool_sort = sort_tools_deterministically(tools);+ if applied.e1_tool_sort {+ tracing::info!(+ event = "e1_applied",+ request_id = %request_id,+ path = "/v1/messages",+ tool_count = tools.len(),+ "tool-array sort applied: tools reordered alphabetically by name"+ );+ }+ }++ // PR-E2: sort each tool's `input_schema` keys recursively.+ // Anthropic schema lives at `tool.input_schema`. Tools without+ // an `input_schema` field are silently skipped — that is a+ // valid Anthropic shape (e.g. zero-argument tools).+ for tool in tools.iter_mut() {+ let Some(schema) = tool.get_mut("input_schema") else {+ continue;+ };+ // We compare bytes before / after to detect whether the+ // sort actually moved any keys (idempotent re-runs report+ // `false` and the caller surfaces no event for the no-op).+ let before = serde_json::to_vec(schema).unwrap_or_default();+ sort_schema_keys_recursive(schema);+ let after = serde_json::to_vec(schema).unwrap_or_default();+ if before != after {+ applied.e2_schema_sort = true;+ }+ }+ if applied.e2_schema_sort {tracing::info!(- event = "e1_applied",+ event = "e2_applied",request_id = %request_id,path = "/v1/messages",tool_count = tools.len(),- "tool-array sort applied: tools reordered alphabetically by name"+ "schema-key sort applied: input_schema keys rewritten in alphabetic order");}@@ -1034,6 +1084,111 @@ mod tests {}}+ #[test]+ fn e2_sorts_input_schema_keys_when_payg() {+ // PAYG, single tool with shuffled input_schema keys → sort+ // should fire (e2 strategy).+ let body = body_of(serde_json::json!({+ "model": "claude",+ "messages": [+ {"role": "user", "content": [+ {"type": "text", "text": "hi"}+ ]}+ ],+ "tools": [+ {+ "name": "search",+ "input_schema": {+ "type": "object",+ "properties": {+ "query": {"type": "string"},+ "filters": {"type": "object"},+ },+ "required": ["query"],+ },+ },+ ],+ }));+ let out = compress_anthropic_request(+ &body,+ CompressionMode::LiveZone,+ CacheControlAutoFrozen::Disabled,+ RequestAuthMode::Payg,+ "req-e2-1",+ );+ match out {+ Outcome::Compressed {+ body: new_body,+ strategies_applied,+ ..+ } => {+ assert!(+ strategies_applied.contains(&"schema_key_sort"),+ "expected schema_key_sort strategy, got: {strategies_applied:?}",+ );+ let parsed: Value = serde_json::from_slice(&new_body).unwrap();+ let schema = &parsed["tools"][0]["input_schema"];+ // Inspect the top-level key sequence directly via the+ // serde_json::Map so we don't accidentally match nested+ // `"type"` occurrences in `find()` calls.+ let map = schema.as_object().unwrap();+ let keys: Vec<&str> = map.keys().map(String::as_str).collect();+ assert_eq!(+ keys,+ vec!["properties", "required", "type"],+ "input_schema top-level keys must be alphabetic; got: {keys:?}"+ );+ }+ other => panic!("expected Compressed with schema sort, got {other:?}"),+ }+ }++ #[test]+ fn e2_runs_even_when_marker_blocks_e1() {+ // PAYG, marker present (E1 skipped), but E2 still runs and+ // mutates schema keys. The dispatch surface should report+ // only `schema_key_sort`, never `tool_array_sort`.+ let body = body_of(serde_json::json!({+ "model": "claude",+ "messages": [+ {"role": "user", "content": [+ {"type": "text", "text": "hi"}+ ]}+ ],+ "tools": [+ {+ "name": "search",+ "cache_control": {"type": "ephemeral"},+ "input_schema": {+ "type": "object",+ "properties": {+ "query": {"type": "string"},+ },+ },+ },+ ],+ }));+ let out = compress_anthropic_request(+ &body,+ CompressionMode::LiveZone,+ CacheControlAutoFrozen::Disabled,+ RequestAuthMode::Payg,+ "req-e2-2",+ );+ match out {+ Outcome::Compressed {+ strategies_applied, ..+ } => {+ assert!(strategies_applied.contains(&"schema_key_sort"));+ assert!(+ !strategies_applied.contains(&"tool_array_sort"),+ "E1 must skip when marker is present; got {strategies_applied:?}",+ );+ }+ other => panic!("expected Compressed with schema sort, got {other:?}"),+ }+ }+#[test]fn e1_already_sorted_idempotent() {// Tools in alphabetic order already — E1 sort is a no-op.@@ -1076,7 +1231,9 @@ mod tests {{strategies_applied:?}",);}- other => panic!("expected Compressed (E3 fires) for already-sorted tools, got {other:?}"),+ other => {+ panic!("expected Compressed (E3 fires) for already-sorted tools, got {other:?}")+ }}}}diff --git a/crates/headroom-proxy/src/compression/live_zone_openai.rs b/crates/headroom-proxy/src/compression/live_zone_openai.rsindex 65f7f49d5..b619403e1 100644--- a/crates/headroom-proxy/src/compression/live_zone_openai.rs+++ b/crates/headroom-proxy/src/compression/live_zone_openai.rs@@ -37,7 +37,7 @@ use headroom_core::transforms::{use serde_json::Value;use crate::cache_stabilization::tool_def_normalize::{- any_tool_has_cache_control, sort_tools_deterministically,+ any_tool_has_cache_control, sort_schema_keys_recursive, sort_tools_deterministically,};use crate::compression::{Outcome, PassthroughReason};use crate::config::CompressionMode;@@ -277,16 +277,16 @@ pub fn compress_openai_chat_request(/// Tracks which Phase E normalization steps mutated the dispatch/// body for the OpenAI Chat path. Mirrors the Anthropic walker's-/// `NormalizationApplied`. Currently carries one flag for PR-E1;-/// PR-E2 lands a second flag in the follow-up commit.+/// `NormalizationApplied`.#[derive(Debug, Clone, Copy, Default)]struct NormalizationApplied {e1_tool_sort: bool,+ e2_schema_sort: bool,}impl NormalizationApplied {fn any(self) -> bool {- self.e1_tool_sort+ self.e1_tool_sort || self.e2_schema_sort}fn strategies(self) -> Vec<&'static str> {@@ -294,14 +294,22 @@ impl NormalizationApplied {if self.e1_tool_sort {out.push("tool_array_sort");}+ if self.e2_schema_sort {+ out.push("schema_key_sort");+ }out}}-/// Apply PR-E1 (tool-array sort) to an OpenAI Chat Completions body-/// when the auth-mode + marker gates clear. Mirrors the Anthropic-/// walker's `normalize_tool_definitions` — same gates, same outcome-/// shape. Module-private; only the dispatcher above calls this.+/// Apply PR-E1 (tool-array sort) and PR-E2 (schema-key sort) to an+/// OpenAI Chat Completions body when the auth-mode + marker gates+/// clear. Mirrors the Anthropic walker's `normalize_tool_definitions`+/// — same gates, same outcome shape. Module-private; only the+/// dispatcher above calls this.+///+/// OpenAI tools nest the schema at `tool.function.parameters` (not+/// `tool.input_schema` like Anthropic) — this is the only walker+/// shape difference between the two providers.fn normalize_tool_definitions_openai_chat(body: &Bytes,parsed: &Value,@@ -317,6 +325,14 @@ fn normalize_tool_definitions_openai_chat(auth_mode = auth_mode.as_str(),"tool-array sort skipped: non-PAYG auth mode passes through byte-equal");+ tracing::info!(+ event = "e2_skipped",+ request_id = %request_id,+ path = "/v1/chat/completions",+ reason = "auth_mode",+ auth_mode = auth_mode.as_str(),+ "schema-key sort skipped: non-PAYG auth mode passes through byte-equal"+ );return (body.clone(), NormalizationApplied::default());}@@ -327,7 +343,8 @@ fn normalize_tool_definitions_openai_chat(return (body.clone(), NormalizationApplied::default());}- if any_tool_has_cache_control(tools_in) {+ let marker_present = any_tool_has_cache_control(tools_in);+ if marker_present {tracing::info!(event = "e1_skipped",request_id = %request_id,@@ -337,7 +354,6 @@ fn normalize_tool_definitions_openai_chat("tool-array sort skipped: customer cache_control marker present \on at least one tool; preserving customer-intentional order");- return (body.clone(), NormalizationApplied::default());}let mut working = parsed.clone();@@ -347,14 +363,42 @@ fn normalize_tool_definitions_openai_chat(.expect("tools array verified above");let mut applied = NormalizationApplied::default();- applied.e1_tool_sort = sort_tools_deterministically(tools);- if applied.e1_tool_sort {++ if !marker_present {+ applied.e1_tool_sort = sort_tools_deterministically(tools);+ if applied.e1_tool_sort {+ tracing::info!(+ event = "e1_applied",+ request_id = %request_id,+ path = "/v1/chat/completions",+ tool_count = tools.len(),+ "tool-array sort applied: tools reordered alphabetically by name"+ );+ }+ }++ // PR-E2: OpenAI tool schema lives at `tool.function.parameters`.+ for tool in tools.iter_mut() {+ let Some(parameters) = tool+ .get_mut("function")+ .and_then(|f| f.get_mut("parameters"))+ else {+ continue;+ };+ let before = serde_json::to_vec(parameters).unwrap_or_default();+ sort_schema_keys_recursive(parameters);+ let after = serde_json::to_vec(parameters).unwrap_or_default();+ if before != after {+ applied.e2_schema_sort = true;+ }+ }+ if applied.e2_schema_sort {tracing::info!(- event = "e1_applied",+ event = "e2_applied",request_id = %request_id,path = "/v1/chat/completions",tool_count = tools.len(),- "tool-array sort applied: tools reordered alphabetically by name"+ "schema-key sort applied: function.parameters keys rewritten in alphabetic order");}diff --git a/crates/headroom-proxy/src/compression/live_zone_responses.rs b/crates/headroom-proxy/src/compression/live_zone_responses.rsindex 92aad25d1..29f02050e 100644--- a/crates/headroom-proxy/src/compression/live_zone_responses.rs+++ b/crates/headroom-proxy/src/compression/live_zone_responses.rs@@ -40,7 +40,7 @@ use headroom_core::transforms::{use serde_json::Value;use crate::cache_stabilization::tool_def_normalize::{- any_tool_has_cache_control, sort_tools_deterministically,+ any_tool_has_cache_control, sort_schema_keys_recursive, sort_tools_deterministically,};use crate::compression::{Outcome, PassthroughReason};use crate::config::CompressionMode;@@ -286,16 +286,16 @@ pub fn compress_openai_responses_request(/// Tracks which Phase E normalization steps mutated the dispatch/// body for the Responses path. Sibling of the same struct in-/// `live_zone_anthropic` and `live_zone_openai`. Currently a single-/// flag for PR-E1; PR-E2 lands a second flag in the follow-up commit.+/// `live_zone_anthropic` and `live_zone_openai`.#[derive(Debug, Clone, Copy, Default)]struct NormalizationApplied {e1_tool_sort: bool,+ e2_schema_sort: bool,}impl NormalizationApplied {fn any(self) -> bool {- self.e1_tool_sort+ self.e1_tool_sort || self.e2_schema_sort}fn strategies(self) -> Vec<&'static str> {@@ -303,14 +303,22 @@ impl NormalizationApplied {if self.e1_tool_sort {out.push("tool_array_sort");}+ if self.e2_schema_sort {+ out.push("schema_key_sort");+ }out}}-/// Apply PR-E1 (tool-array sort) to a Responses request body when-/// the auth-mode + marker gates clear. Mirrors the same gate logic-/// as the Anthropic / Chat Completions walkers — same skip events,-/// same outcome shape, same byte-equal passthrough on non-PAYG.+/// Apply PR-E1 (tool-array sort) and PR-E2 (schema-key sort) to a+/// Responses request body when the auth-mode + marker gates clear.+/// Mirrors the same gate logic as the Anthropic / Chat Completions+/// walkers — same skip events, same outcome shape, same byte-equal+/// passthrough on non-PAYG.+///+/// Responses tools nest the schema at `tool.function.parameters`+/// (same as OpenAI Chat Completions, distinct from Anthropic's+/// `tool.input_schema`).fn normalize_tool_definitions_responses(body: &Bytes,parsed: &Value,@@ -326,6 +334,14 @@ fn normalize_tool_definitions_responses(auth_mode = auth_mode.as_str(),"tool-array sort skipped: non-PAYG auth mode passes through byte-equal");+ tracing::info!(+ event = "e2_skipped",+ request_id = %request_id,+ path = "/v1/responses",+ reason = "auth_mode",+ auth_mode = auth_mode.as_str(),+ "schema-key sort skipped: non-PAYG auth mode passes through byte-equal"+ );return (body.clone(), NormalizationApplied::default());}@@ -336,7 +352,8 @@ fn normalize_tool_definitions_responses(return (body.clone(), NormalizationApplied::default());}- if any_tool_has_cache_control(tools_in) {+ let marker_present = any_tool_has_cache_control(tools_in);+ if marker_present {tracing::info!(event = "e1_skipped",request_id = %request_id,@@ -346,7 +363,6 @@ fn normalize_tool_definitions_responses("tool-array sort skipped: customer cache_control marker present \on at least one tool; preserving customer-intentional order");- return (body.clone(), NormalizationApplied::default());}let mut working = parsed.clone();@@ -356,14 +372,42 @@ fn normalize_tool_definitions_responses(.expect("tools array verified above");let mut applied = NormalizationApplied::default();- applied.e1_tool_sort = sort_tools_deterministically(tools);- if applied.e1_tool_sort {++ if !marker_present {+ applied.e1_tool_sort = sort_tools_deterministically(tools);+ if applied.e1_tool_sort {+ tracing::info!(+ event = "e1_applied",+ request_id = %request_id,+ path = "/v1/responses",+ tool_count = tools.len(),+ "tool-array sort applied: tools reordered alphabetically by name"+ );+ }+ }++ // PR-E2: Responses tool schema lives at `tool.function.parameters`.+ for tool in tools.iter_mut() {+ let Some(parameters) = tool+ .get_mut("function")+ .and_then(|f| f.get_mut("parameters"))+ else {+ continue;+ };+ let before = serde_json::to_vec(parameters).unwrap_or_default();+ sort_schema_keys_recursive(parameters);+ let after = serde_json::to_vec(parameters).unwrap_or_default();+ if before != after {+ applied.e2_schema_sort = true;+ }+ }+ if applied.e2_schema_sort {tracing::info!(- event = "e1_applied",+ event = "e2_applied",request_id = %request_id,path = "/v1/responses",tool_count = tools.len(),- "tool-array sort applied: tools reordered alphabetically by name"+ "schema-key sort applied: function.parameters keys rewritten in alphabetic order");}diff --git a/crates/headroom-proxy/tests/integration_schema_sort.rs b/crates/headroom-proxy/tests/integration_schema_sort.rsnew file mode 100644index 000000000..84ec7c51b--- /dev/null+++ b/crates/headroom-proxy/tests/integration_schema_sort.rs@@ -0,0 +1,267 @@+//! Integration tests for PR-E2: recursive JSON Schema key sort.+//!+//! Boots a real Rust proxy in front of a wiremock upstream. Three+//! scenarios:+//!+//! 1. **PAYG path**: a tool's `input_schema` arrives at the upstream+//! with keys sorted alphabetically at every nesting level. Array+//! order in `oneOf` etc. is preserved.+//! 2. **OAuth path**: schema keys pass through verbatim — bytes the+//! upstream sees match the bytes the client sent (SHA-256+//! byte-equal).+//! 3. **PAYG, marker present**: PR-E1 (sort) is skipped, but PR-E2+//! still runs on the schema. Tools array preserves customer+//! order; schema keys are sorted.+//!+//! The Phase A cache-safety invariant — bytes-in == bytes-out for+//! any non-PAYG request — is the contract under test.++mod common;++use common::start_proxy_with;+use serde_json::{json, Value};+use sha2::{Digest, Sha256};+use std::sync::{Arc, Mutex};+use wiremock::matchers::{method, path};+use wiremock::{Mock, MockServer, ResponseTemplate};++fn sha256_hex(bytes: &[u8]) -> String {+ let mut hasher = Sha256::new();+ hasher.update(bytes);+ let digest = hasher.finalize();+ let mut s = String::with_capacity(64);+ for b in digest {+ s.push_str(&format!("{b:02x}"));+ }+ s+}++async fn mount_anthropic_capture(upstream: &MockServer) -> Arc<Mutex<Option<Vec<u8>>>> {+ let captured: Arc<Mutex<Option<Vec<u8>>>> = Arc::new(Mutex::new(None));+ let captured_clone = captured.clone();+ Mock::given(method("POST"))+ .and(path("/v1/messages"))+ .respond_with(move |req: &wiremock::Request| {+ *captured_clone.lock().unwrap() = Some(req.body.clone());+ ResponseTemplate::new(200).set_body_string(r#"{"ok":true}"#)+ })+ .mount(upstream)+ .await;+ captured+}++/// PAYG: schema arrives with keys in a hash-randomized order; assert+/// upstream sees them sorted at every nesting level. Array order in+/// `oneOf` is preserved.+#[tokio::test]+async fn payg_request_with_shuffled_schema_keys_arrives_sorted() {+ let upstream = MockServer::start().await;+ let captured = mount_anthropic_capture(&upstream).await;+ let proxy = start_proxy_with(&upstream.uri(), |c| {+ c.compression = true;+ c.compression_mode = headroom_proxy::config::CompressionMode::LiveZone;+ })+ .await;++ let payload = json!({+ "model": "claude-3-5-sonnet-20241022",+ "max_tokens": 32,+ "messages": [{"role": "user", "content": "hi"}],+ "tools": [+ {+ "name": "search",+ "input_schema": {+ // Top-level keys in non-alphabetic order.+ "type": "object",+ "required": ["query"],+ "properties": {+ // Nested keys also shuffled.+ "z_filter": {"type": "object"},+ "query": {"type": "string"},+ "a_field": {"type": "integer"},+ },+ // Array semantics test: oneOf must stay in order.+ "oneOf": [+ {"const": "third"},+ {"const": "first"},+ {"const": "second"},+ ],+ },+ },+ ],+ });+ let body = serde_json::to_vec(&payload).unwrap();+ let resp = reqwest::Client::new()+ .post(format!("{}/v1/messages", proxy.url()))+ .header("x-api-key", "sk-ant-api03-abc")+ .header("content-type", "application/json")+ .body(body)+ .send()+ .await+ .unwrap();+ assert_eq!(resp.status(), 200);++ let upstream_body = captured+ .lock()+ .unwrap()+ .clone()+ .expect("upstream should have captured");+ let parsed: Value = serde_json::from_slice(&upstream_body).expect("upstream body is JSON");+ let schema = &parsed["tools"][0]["input_schema"];++ // Top-level: oneOf, properties, required, type (alphabetic).+ let top_map = schema.as_object().unwrap();+ let top_keys: Vec<&str> = top_map.keys().map(String::as_str).collect();+ assert_eq!(top_keys, vec!["oneOf", "properties", "required", "type"]);++ // Nested properties: a_field, query, z_filter (alphabetic).+ let props = schema["properties"].as_object().unwrap();+ let prop_keys: Vec<&str> = props.keys().map(String::as_str).collect();+ assert_eq!(prop_keys, vec!["a_field", "query", "z_filter"]);++ // oneOf array order preserved (NOT sorted).+ let one_of = schema["oneOf"].as_array().unwrap();+ let consts: Vec<&str> = one_of+ .iter()+ .map(|v| v.get("const").and_then(Value::as_str).unwrap())+ .collect();+ assert_eq!(consts, vec!["third", "first", "second"]);++ proxy.shutdown().await;+}++/// OAuth: bytes pass through verbatim — SHA-256 byte-equal.+#[tokio::test]+async fn oauth_request_passes_schema_through_byte_equal() {+ let upstream = MockServer::start().await;+ let captured = mount_anthropic_capture(&upstream).await;+ let proxy = start_proxy_with(&upstream.uri(), |c| {+ c.compression = true;+ c.compression_mode = headroom_proxy::config::CompressionMode::LiveZone;+ })+ .await;++ let payload = json!({+ "model": "claude-3-5-sonnet-20241022",+ "max_tokens": 32,+ "messages": [{"role": "user", "content": "hi"}],+ "tools": [+ {+ "name": "search",+ "input_schema": {+ "type": "object",+ "required": ["query"],+ "properties": {+ "z_filter": {"type": "object"},+ "query": {"type": "string"},+ },+ },+ },+ ],+ });+ let body = serde_json::to_vec(&payload).unwrap();+ let body_hash = sha256_hex(&body);++ let resp = reqwest::Client::new()+ .post(format!("{}/v1/messages", proxy.url()))+ .header("authorization", "Bearer sk-ant-oat-foo")+ .header("content-type", "application/json")+ .body(body)+ .send()+ .await+ .unwrap();+ assert_eq!(resp.status(), 200);++ let upstream_body = captured+ .lock()+ .unwrap()+ .clone()+ .expect("upstream should have captured");+ assert_eq!(+ sha256_hex(&upstream_body),+ body_hash,+ "OAuth path must pass schema bytes through unchanged"+ );++ proxy.shutdown().await;+}++/// PAYG, marker present: E1 (sort) is skipped → tools array order+/// preserved. E2 (schema sort) still runs because the marker lives on+/// the tool object, not inside the schema.+#[tokio::test]+async fn payg_with_marker_runs_e2_but_not_e1() {+ let upstream = MockServer::start().await;+ let captured = mount_anthropic_capture(&upstream).await;+ let proxy = start_proxy_with(&upstream.uri(), |c| {+ c.compression = true;+ c.compression_mode = headroom_proxy::config::CompressionMode::LiveZone;+ })+ .await;++ let payload = json!({+ "model": "claude-3-5-sonnet-20241022",+ "max_tokens": 32,+ "messages": [{"role": "user", "content": "hi"}],+ "tools": [+ {+ "name": "zebra",+ "cache_control": {"type": "ephemeral"},+ "input_schema": {+ "type": "object",+ "required": ["q"],+ "properties": {"q": {"type": "string"}},+ },+ },+ {+ "name": "apple",+ "input_schema": {+ "type": "object",+ "required": ["x"],+ "properties": {"x": {"type": "string"}},+ },+ },+ ],+ });+ let body = serde_json::to_vec(&payload).unwrap();+ let resp = reqwest::Client::new()+ .post(format!("{}/v1/messages", proxy.url()))+ .header("x-api-key", "sk-ant-api03-abc")+ .header("content-type", "application/json")+ .body(body)+ .send()+ .await+ .unwrap();+ assert_eq!(resp.status(), 200);++ let upstream_body = captured+ .lock()+ .unwrap()+ .clone()+ .expect("upstream should have captured");+ let parsed: Value = serde_json::from_slice(&upstream_body).unwrap();++ // E1 skipped: tools order preserved (zebra still first).+ let tools = parsed["tools"].as_array().unwrap();+ let names: Vec<&str> = tools.iter().map(|t| t["name"].as_str().unwrap()).collect();+ assert_eq!(names, vec!["zebra", "apple"]);++ // E2 ran: input_schema keys are sorted on every tool, including+ // the one carrying the marker.+ for (i, _) in tools.iter().enumerate() {+ let schema = &parsed["tools"][i]["input_schema"];+ let keys: Vec<&str> = schema+ .as_object()+ .unwrap()+ .keys()+ .map(String::as_str)+ .collect();+ assert_eq!(+ keys,+ vec!["properties", "required", "type"],+ "schema keys must be sorted on tools[{i}]"+ );+ }++ proxy.shutdown().await;+}