feat: add cache routing alignment and usage visibility for 2.5.0

tests/unit/test_cache_affinity.py

@@ -3,6 +3,8 @@ from types import SimpleNamespace
 from uuid import uuid4
 import re
 
+import pytest
+
 from artemis.llm.cache_affinity import cache_affinity_options
 
 
@@ -53,3 +55,35 @@ def test_concurrent_calls_do_not_share_or_mutate_task_headers():
         )
     assert results[0]["extra_headers"]["Thread-Id"] != results[1]["extra_headers"]["Thread-Id"]
     assert shared == {"extra_headers": {"X-Test": "shared"}}
+
+
+@pytest.mark.parametrize("name", ["Thread-Id", "THREAD_ID", "session-id", "Session_id"])
+def test_header_only_override_aligns_body_and_missing_headers(name):
+    headers = {name: "caller-conversation", "X-Test": "untouched"}
+    actual = cache_affinity_options(context("task"), "flash", "test", {"extra_headers": headers})
+    assert actual["prompt_cache_key"] == "caller-conversation"
+    routing = {
+        key.lower().replace("_", "-"): value for key, value in actual["extra_headers"].items()
+    }
+    assert routing["thread-id"] == routing["session-id"] == actual["prompt_cache_key"]
+    assert headers == {name: "caller-conversation", "X-Test": "untouched"}
+    assert cache_affinity_options(None, None, None, {"extra_headers": headers}) == actual
+
+
+def test_explicit_body_and_header_options_are_not_overwritten():
+    options = {
+        "prompt_cache_key": "body-override",
+        "extra_headers": {"thread_id": "header-override"},
+    }
+    actual = cache_affinity_options(context("task"), "flash", "test", options)
+    assert actual["prompt_cache_key"] == "body-override"
+    assert actual["extra_headers"]["thread_id"] == "header-override"
+    assert "Thread-Id" not in actual["extra_headers"]
+
+
+@pytest.mark.parametrize("value", [None, "", "unsafe\r\nheader", "a" * 129])
+def test_invalid_header_is_not_promoted_to_body(value):
+    actual = cache_affinity_options(
+        context("task"), "flash", "test", {"extra_headers": {"Thread-Id": value}}
+    )
+    assert actual["prompt_cache_key"].startswith("artemis:")