Skip to content

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.

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.rs
index 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 tool
diff --git a/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs b/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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;
+}