prefixwise 0.3.0__py3-none-any.whl

prefixwise/diagnostics.py

@@ -0,0 +1,168 @@
+"""Native provider diagnostics chaining (v2).
+
+The proxy auto-chains the provider's own diagnostic identifier so the
+provider's miss reason is recorded beside Prefixwise's cause on every
+turn. The provider reason is a *partial agreement signal*, not ground
+truth: providers report the earliest divergence only, in a coarse
+taxonomy, and neither names TTL expiry, routing, or eviction.
+
+Anthropic (Claude API only, not Bedrock / Google-managed):
+- GA Sep 23, 2026. The beta header ``cache-diagnosis-2026-04-07`` is
+  NO LONGER REQUIRED. Send ``diagnostics: {"previous_message_id": id}``
+  (first turn: null to opt in). Chaining does not change caching
+  behaviour or load prior content. ZDR-eligible.
+- Reasons (6): model_changed, system_changed, tools_changed,
+  messages_changed, previous_message_not_found, unavailable.
+  ``unavailable`` fires when model/system/tools match but tool_choice,
+  thinking, context_management, output_config, output_format, or beta
+  headers differ: that is PARAM_RENDERED.
+
+OpenAI (Responses API only, GPT-5.6+):
+- Send ``prompt_cache_options.comparison_response_id`` with a baseline
+  response id. Does not load the conversation or change caching.
+  Streaming: read ``prompt_cache_diagnostics`` from ``event.response``
+  in the ``response.completed`` event.
+- Types (4): cache_hit, cache_miss, comparison_response_not_found,
+  unavailable. Reasons (9): model_changed, prompt_cache_key_changed,
+  service_tier_changed, tools_changed, text_format_changed,
+  reasoning_effort_changed, verbosity_changed, context_compacted,
+  input_changed. No TTL-expiry or routing reason exists.
+
+Gemini: no miss diagnostics (verified Nov 2026). Only a hit count.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .classifier import MissCause
+
+ANTHROPIC_REASONS = {
+    "model_changed": MissCause.MODEL_SWITCH,
+    "system_changed": MissCause.SYSTEM_EDIT,
+    "tools_changed": MissCause.TOOL_CATALOG_CHANGE,  # or TOOL_RESERIALIZE; ambiguous, see below
+    "messages_changed": MissCause.HISTORY_EDIT,  # or COMPACTION_REWRITE; hook decides
+    "previous_message_not_found": MissCause.UNKNOWN,
+    "unavailable": MissCause.PARAM_RENDERED,
+}
+
+OPENAI_REASONS = {
+    "model_changed": MissCause.MODEL_SWITCH,
+    "prompt_cache_key_changed": MissCause.UNKNOWN,
+    "service_tier_changed": MissCause.ROUTING_MISS,
+    "tools_changed": MissCause.TOOL_CATALOG_CHANGE,
+    "text_format_changed": MissCause.PARAM_RENDERED,
+    "reasoning_effort_changed": MissCause.PARAM_RENDERED,
+    "verbosity_changed": MissCause.PARAM_RENDERED,
+    "context_compacted": MissCause.COMPACTION_REWRITE,
+    "input_changed": MissCause.HISTORY_EDIT,
+}
+
+
+def anthropic_diagnostics(previous_message_id: str | None) -> dict:
+    """Build the Anthropic diagnostics object. No beta header needed (GA Sep 23 2026)."""
+    return {"diagnostics": {"previous_message_id": previous_message_id}}
+
+
+def openai_comparison_options(comparison_response_id: str | None) -> dict:
+    """Build OpenAI prompt_cache_options for diagnostics chaining."""
+    if comparison_response_id is None:
+        return {}
+    return {"prompt_cache_options": {"comparison_response_id": comparison_response_id}}
+
+
+# Provider reasons are coarse; Prefixwise causes refine them. A Prefixwise
+# cause agrees with a native reason when it is one of the causes that
+# reason covers: Anthropic's system_changed covers both a wording edit and
+# a date-only change; OpenAI's input_changed covers any change to the
+# prompt input (instructions, history, tool output, compaction). Each set
+# lists only causes that are a kind of that reason, never a different
+# block, so agreement still requires naming the right place.
+_CONTENT_CHANGES = {MissCause.HISTORY_EDIT, MissCause.COMPACTION_REWRITE, MissCause.TOOL_RESULT_MUTATION}
+_SYSTEM_CHANGES = {MissCause.SYSTEM_EDIT, MissCause.VOLATILE_SYSTEM}
+_TOOL_CHANGES = {MissCause.TOOL_RESERIALIZE, MissCause.TOOL_CATALOG_CHANGE}
+
+NATIVE_COVERS = {
+    "anthropic": {
+        "model_changed": {MissCause.MODEL_SWITCH},
+        "system_changed": _SYSTEM_CHANGES,
+        "tools_changed": _TOOL_CHANGES,
+        "messages_changed": _CONTENT_CHANGES,
+        "previous_message_not_found": {MissCause.UNKNOWN},
+        "unavailable": {MissCause.PARAM_RENDERED},
+    },
+    "openai": {
+        "model_changed": {MissCause.MODEL_SWITCH},
+        "prompt_cache_key_changed": {MissCause.ROUTING_MISS, MissCause.UNKNOWN},
+        "service_tier_changed": {MissCause.ROUTING_MISS, MissCause.PARAM_RENDERED},
+        "tools_changed": _TOOL_CHANGES,
+        "text_format_changed": {MissCause.PARAM_RENDERED},
+        "reasoning_effort_changed": {MissCause.PARAM_RENDERED},
+        "verbosity_changed": {MissCause.PARAM_RENDERED},
+        "context_compacted": {MissCause.COMPACTION_REWRITE},
+        "input_changed": _CONTENT_CHANGES | _SYSTEM_CHANGES,
+    },
+}
+
+
+def native_covers(provider: str, reason: str | None) -> set[MissCause] | None:
+    """The Prefixwise causes a native reason covers, or None if unmapped."""
+    if reason is None:
+        return None
+    return NATIVE_COVERS.get(provider, {}).get(reason)
+
+
+def map_native_reason(provider: str, reason: str | None) -> MissCause | None:
+    if reason is None:
+        return None
+    table = {"anthropic": ANTHROPIC_REASONS, "openai": OPENAI_REASONS}.get(provider, {})
+    return table.get(reason)
+
+
+@dataclass
+class AgreementScorer:
+    """Score the classifier against native reasons where both exist.
+
+    Two metrics ship with the classifier:
+    - agreement: share of turns where Prefixwise's cause maps onto the
+      native reason when both exist (E1 target >= 95%).
+    - coverage: share of misses not UNKNOWN (E1 target: UNKNOWN <= 10%).
+    A miss providers lump into ``unavailable`` that Prefixwise names
+    PARAM_RENDERED counts as agreement when the parameter diff is
+    present in the request.
+    """
+
+    total_with_native: int = 0
+    agreed: int = 0
+    total_misses: int = 0
+    unknown_misses: int = 0
+
+    def record(self, cause: MissCause, native_reason: str | None, provider: str) -> bool | None:
+        """Record one turn. Returns True/False for agreement, None if no native reason."""
+        is_miss = cause not in (MissCause.NONE, MissCause.FIRST_WRITE)
+        if is_miss:
+            self.total_misses += 1
+            if cause is MissCause.UNKNOWN:
+                self.unknown_misses += 1
+        if native_reason is None:
+            return None
+        covered = native_covers(provider, native_reason)
+        if covered is None:
+            return None
+        self.total_with_native += 1
+        agreed = cause in covered
+        if agreed:
+            self.agreed += 1
+        return agreed
+
+    @property
+    def agreement_rate(self) -> float | None:
+        if not self.total_with_native:
+            return None
+        return self.agreed / self.total_with_native
+
+    @property
+    def unknown_rate(self) -> float | None:
+        if not self.total_misses:
+            return None
+        return self.unknown_misses / self.total_misses

prefixwise/explain.py

@@ -0,0 +1,155 @@
+"""Offline miss explanation: why would (or did) the cache miss between two requests?
+
+No proxy, no API key. Give it request bodies as the client sent them,
+optionally with the usage the provider returned, and it runs the same
+fingerprinting and classifier as the proxy.
+
+Without usage, the explanation is about the prompt itself: it assumes the
+cache would have served the whole shared prefix, so the answer is "what in
+the request breaks reuse", not "what the provider actually did". TTL
+expiry, eviction, and routing need real usage or engine events.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .classifier import RequestSnapshot, classify
+from .fingerprint import BlockFingerprint, Fingerprinter
+from .proxy import (cache_ttl_seconds, completion_tokens_of, extract_blocks, has_cache_breakpoint,
+                    normalize_usage)
+
+PARAM_KEYS = ("tool_choice", "thinking", "reasoning", "output_format", "text_format", "verbosity")
+
+
+def detect_provider(body: dict) -> str:
+    """Anthropic Messages bodies carry system at the top level; OpenAI ones do not."""
+    return "anthropic" if "system" in body else "openai"
+
+
+@dataclass
+class Turn:
+    body: dict
+    usage: dict | None = None
+    compaction_event: bool = False
+    gap_seconds: float | None = None
+    session_id: str = "default"
+
+
+@dataclass
+class Explanation:
+    cause: str
+    legit: bool | None
+    evidence: str
+    divergence: dict | None
+    provider: str
+    offline: bool
+    prompt_tokens: int | None = None
+    cached_tokens: int | None = None
+    secondary: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return dict(self.__dict__)
+
+
+def first_divergence(prev: list[BlockFingerprint], curr: list[BlockFingerprint]) -> dict | None:
+    """Locate the first block, in prefix order, where two requests differ."""
+    for i, (a, b) in enumerate(zip(prev, curr)):
+        if a.role != b.role:
+            return {"index": i, "role": f"{a.role} -> {b.role}", "kind": "block order changed"}
+        if a.raw == b.raw:
+            continue
+        if a.canonical == b.canonical:
+            kind = "same content, different bytes (key order / whitespace / serialization)"
+        elif a.masked == b.masked:
+            kind = "only volatile values changed (dates, times, ids, numbers)"
+        else:
+            kind = "content changed"
+        return {"index": i, "role": a.role, "kind": kind}
+    if len(curr) > len(prev):
+        return {"index": len(prev), "role": curr[len(prev)].role,
+                "kind": "appended after the previous request (normal growth, not a divergence)"}
+    if len(curr) < len(prev):
+        return {"index": len(curr), "role": prev[len(curr)].role,
+                "kind": "previous blocks removed (history truncated or compacted)"}
+    return None
+
+
+def _snapshot(turn: Turn, provider: str, fp: Fingerprinter) -> RequestSnapshot:
+    blocks = fp.fingerprint_blocks(extract_blocks(turn.body, provider))
+    if turn.usage is not None:
+        prompt, cached = normalize_usage(provider, turn.usage)
+        min_prefix = None
+    else:
+        # Offline: pretend the shared prefix was fully served, so only a
+        # divergence in the request itself can explain a miss.
+        prompt, cached, min_prefix = 1, 1, 0
+    return RequestSnapshot(model=str(turn.body.get("model", "unknown")), provider=provider,
+                           blocks=blocks, prompt_tokens=prompt, cached_tokens=cached,
+                           gap_seconds=turn.gap_seconds, compaction_event=turn.compaction_event,
+                           params={k: turn.body.get(k) for k in PARAM_KEYS if turn.body.get(k) is not None},
+                           has_breakpoint=has_cache_breakpoint(turn.body),
+                           ttl_seconds=cache_ttl_seconds(provider, turn.body),
+                           min_prefix_tokens=min_prefix)
+
+
+def explain_pair(prev: Turn | None, curr: Turn, provider: str | None = None,
+                 fingerprinter: Fingerprinter | None = None) -> Explanation:
+    provider = provider or detect_provider(curr.body)
+    fp = fingerprinter or Fingerprinter()
+    curr_snap = _snapshot(curr, provider, fp)
+    prev_snap = _snapshot(prev, provider, fp) if prev is not None else None
+    result = classify(prev_snap, curr_snap)
+    div = first_divergence(prev_snap.blocks, curr_snap.blocks) if prev_snap else None
+    if div and result.cause.value == "tool_reserialize" and div["kind"] == "content changed":
+        div["kind"] = "tools reordered (same tool set, different order)"
+    return Explanation(cause=result.cause.value, legit=result.legit, evidence=result.evidence,
+                       divergence=div, provider=provider, offline=curr.usage is None,
+                       prompt_tokens=curr_snap.prompt_tokens if curr.usage is not None else None,
+                       cached_tokens=curr_snap.cached_tokens if curr.usage is not None else None,
+                       secondary=[c.value for c in result.secondary])
+
+
+def _turn_from_record(rec: dict) -> Turn:
+    """A record is a bare request body, or {"request"|"body": ..., "usage": ..., ...}."""
+    if not isinstance(rec, dict):
+        raise ValueError("each record must be a JSON object")
+    body = rec.get("request") or rec.get("body")
+    if body is None:
+        return Turn(body=rec, session_id=str(rec.get("session_id") or "default"))
+    usage = rec.get("usage") or (rec.get("response") or {}).get("usage")
+    return Turn(body=body, usage=usage,
+                compaction_event=bool(rec.get("compaction_event", False)),
+                gap_seconds=rec.get("gap_seconds"),
+                session_id=str(rec.get("session_id") or body.get("session_id") or "default"))
+
+
+def load_turns(path: str | Path) -> list[Turn]:
+    """Load one JSON record, a JSON array of records, or JSONL (one record per line)."""
+    text = Path(path).read_text()
+    stripped = text.strip()
+    if not stripped:
+        return []
+    try:
+        data = json.loads(stripped)
+    except ValueError:
+        data = [json.loads(line) for line in text.splitlines() if line.strip()]
+    records = data if isinstance(data, list) else [data]
+    return [_turn_from_record(r) for r in records]
+
+
+def explain_session(turns: list[Turn], provider: str | None = None) -> list[Explanation]:
+    """Explain every turn against the previous turn in the same session."""
+    fp = Fingerprinter()
+    last: dict[str, Turn] = {}
+    out = []
+    for t in turns:
+        out.append(explain_pair(last.get(t.session_id), t, provider, fp))
+        last[t.session_id] = t
+    return out
+
+
+__all__ = ["Turn", "Explanation", "explain_pair", "explain_session", "load_turns",
+           "first_divergence", "detect_provider", "completion_tokens_of"]

prefixwise/fingerprint.py

@@ -0,0 +1,159 @@
+"""Canonical block fingerprinting (v2).
+
+Split a rendered request into blocks in prefix order and store three
+hashes per block:
+
+- ``raw``: SHA-256 (or HMAC) over the exact bytes as sent. This is the
+  only hash that can see TOOL_RESERIALIZE, which is defined as
+  canonical-equal, raw-different.
+- ``canonical``: SHA-256 (or HMAC) over canonicalised bytes (sorted keys,
+  fixed separators, NFC unicode, no trailing-whitespace variance).
+- ``masked``: hash over canonical bytes with volatile values masked out
+  (dates, times, numbers, UUIDs, ids). A system block whose raw hash
+  changed but whose masked hash is equal is VOLATILE_SYSTEM, not a
+  SYSTEM_EDIT.
+
+Hashes are stored, never raw prompts, by default.
+
+Privacy: a bare hash of a short or predictable block (a four-word user
+message, a boilerplate system line) is dictionary-guessable. When an
+HMAC key is supplied, every hash of a short/predictable block is an
+HMAC with the per-install key, replacing bare SHA-256 entirely for
+that block (raw, canonical, and masked). The short-block threshold
+is a policy choice (default 64 tokens, approximate, ~256 characters),
+not a verified fact; a 60-token boilerplate line can still be
+predictable, and a long block can still be guessable.
+
+Soft tokens / summaries are fingerprinted as distinct block types:
+their content is never hashed as text. A soft-token block hashes
+only its type and token count.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac as hmac_mod
+import json
+import re
+import unicodedata
+from dataclasses import dataclass, field
+
+BLOCK_ROLES = (
+    "system",
+    "system_dynamic",
+    "tools",
+    "messages",
+    "tool_results",
+    "user",
+    "summary",
+    "soft_tokens",
+)
+
+# Policy choice, not a verified fact (see module docstring).
+DEFAULT_SHORT_BLOCK_CHARS = 256
+
+_DATE_RE = re.compile(r"\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?")
+_TIME_RE = re.compile(r"\b\d{1,2}:\d{2}(?::\d{2})?(?:\s*[AP]M)?\b", re.IGNORECASE)
+_UUID_RE = re.compile(r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b")
+_HEX_ID_RE = re.compile(r"\b[0-9a-fA-F]{16,}\b")
+_NUMBER_RE = re.compile(r"\b\d+(?:\.\d+)?\b")
+_TOKEN_WITH_DIGIT_RE = re.compile(r"\b\w*\d\w*\b")
+
+
+def mask_volatiles(text: str) -> str:
+    """Replace volatile values (dates, times, ids, numbers) with placeholders."""
+    text = _DATE_RE.sub("<DATE>", text)
+    text = _TIME_RE.sub("<TIME>", text)
+    text = _UUID_RE.sub("<ID>", text)
+    text = _HEX_ID_RE.sub("<ID>", text)
+    text = _NUMBER_RE.sub("<N>", text)
+    # Tokens like abc123 / session-42 are ids, not stable words.
+    text = _TOKEN_WITH_DIGIT_RE.sub("<ID>", text)
+    return text
+
+
+def canonical_bytes(value: object) -> bytes:
+    text = json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    text = unicodedata.normalize("NFC", text)
+    return text.encode("utf-8")
+
+
+def raw_bytes(value: object) -> bytes:
+    """Exact bytes as sent: JSON without key sorting, as the caller rendered it."""
+    if isinstance(value, (str, bytes)):
+        raw = value if isinstance(value, bytes) else value.encode("utf-8")
+    else:
+        raw = json.dumps(value, ensure_ascii=False).encode("utf-8")
+    return raw
+
+
+def _hash(data: bytes, hmac_key: bytes | None) -> str:
+    if hmac_key:
+        return hmac_mod.new(hmac_key, data, hashlib.sha256).hexdigest()
+    return hashlib.sha256(data).hexdigest()
+
+
+@dataclass
+class BlockFingerprint:
+    role: str
+    index: int
+    raw: str
+    canonical: str
+    masked: str
+    byte_length: int
+    hmac: bool = False
+    # First-divergence position in tokens is filled by the caller when a
+    # tokenizer is available; None means "not measured", never a guess.
+    token_estimate: int | None = None
+
+
+@dataclass
+class Fingerprinter:
+    """Per-install fingerprinter. Supply hmac_key to protect short blocks."""
+
+    hmac_key: bytes | None = None
+    short_block_chars: int = DEFAULT_SHORT_BLOCK_CHARS
+
+    def _is_short(self, raw: bytes) -> bool:
+        return len(raw) <= self.short_block_chars
+
+    def fingerprint_block(self, role: str, index: int, value: object) -> BlockFingerprint:
+        if role == "soft_tokens":
+            # Never hash soft-token content as text: hash type + count only.
+            count = value if isinstance(value, int) else len(value)  # type: ignore[arg-type]
+            payload = canonical_bytes({"type": "soft_tokens", "count": count})
+            digest = _hash(payload, self.hmac_key)
+            return BlockFingerprint(role=role, index=index, raw=digest, canonical=digest,
+                                    masked=digest, byte_length=len(payload), hmac=bool(self.hmac_key))
+        raw = raw_bytes(value)
+        canon = canonical_bytes(value)
+        masked_text = mask_volatiles(canon.decode("utf-8", "replace"))
+        masked = masked_text.encode("utf-8")
+        # HMAC replaces bare hashing for short/predictable blocks entirely.
+        key = self.hmac_key if self._is_short(raw) else None
+        return BlockFingerprint(
+            role=role, index=index,
+            raw=_hash(raw, key), canonical=_hash(canon, key), masked=_hash(masked, key),
+            byte_length=len(raw), hmac=bool(key),
+        )
+
+    def fingerprint_blocks(self, blocks: list[tuple[str, object]]) -> list[BlockFingerprint]:
+        return [self.fingerprint_block(role, i, value) for i, (role, value) in enumerate(blocks)]
+
+    def prefix_hash(self, fingerprints: list[BlockFingerprint]) -> str:
+        joined = "".join(f.canonical for f in fingerprints).encode("utf-8")
+        return _hash(joined, self.hmac_key)
+
+
+def block_hash(value: object) -> str:
+    """Backwards-compatible helper: canonical SHA-256 of a value."""
+    return hashlib.sha256(canonical_bytes(value)).hexdigest()
+
+
+def fingerprint_blocks(blocks: list[tuple[str, object]], hmac_key: bytes | None = None) -> list[BlockFingerprint]:
+    return Fingerprinter(hmac_key=hmac_key).fingerprint_blocks(blocks)
+
+
+def prefix_hash(fingerprints: list[BlockFingerprint]) -> str:
+    joined = "".join(f.canonical for f in fingerprints).encode("utf-8")
+    return hashlib.sha256(joined).hexdigest()

prefixwise/fixes.py

@@ -0,0 +1,105 @@
+"""Fix toggles and fix advice.
+
+A toggle is a rewrite the proxy can apply to a request before forwarding
+it, opt-in and reversible (turn it off and requests go through unchanged).
+Only rewrites that cannot change what the prompt means are toggles:
+
+- canonical_tools: tools sorted by name, each tool's keys sorted. The
+  provider caches by exact prefix, and tools come first in every
+  provider's prefix, so a tool list whose order or key order drifts
+  between turns (plugin load order, dict/set iteration, a framework
+  rebuilding definitions) misses the whole cache. Sorting is stable:
+  same tool set, same bytes, every turn.
+
+Everything else is advice: changes only the application can make safely
+(moving a timestamp out of the system prompt changes the text the model
+reads). FIX_ADVICE maps each wasteful cause to its fix, and says whether
+the proxy can apply it.
+
+A fix ships as "recommended" on predicted savings (the avoidable tokens
+the ledger attributes to its cause) and is "proven" only after a replay
+(experiments/e4) shows realised savings of at least half the prediction
+with task success flat.
+"""
+
+from __future__ import annotations
+
+import json
+
+AVAILABLE_FIXES = ("canonical_tools",)
+
+# Evidence per fix. Change only with a committed E4 run behind it.
+FIX_STATUS = {
+    "canonical_tools": {
+        "status": "proven",
+        "evidence": "E4 live 2026-11-06: 99.9% of predicted savings realised on Anthropic (Haiku 5.5), "
+                    "97.5% on vLLM (Qwen3-4B); task success flat (0/60 and 1/60 turns changed). "
+                    "experiments/e4/runs/2026-11-06-live.md",
+    },
+}
+
+
+def _tool_name(tool: object) -> str | None:
+    if not isinstance(tool, dict):
+        return None
+    fn = tool.get("function")
+    if isinstance(fn, dict) and fn.get("name"):
+        return str(fn["name"])  # OpenAI chat completions
+    return str(tool["name"]) if tool.get("name") else None  # Anthropic, Responses API
+
+
+def _sorted_keys(value: object) -> object:
+    # json round trip with sort_keys: nested dicts come back in sorted key order.
+    return json.loads(json.dumps(value, sort_keys=True))
+
+
+def canonical_tools(tools: list) -> list:
+    """Tools sorted by name (unnamed tools keep their order, at the end),
+    with every tool's keys sorted. Same set in, same bytes out."""
+    named = sorted((t for t in tools if _tool_name(t) is not None), key=_tool_name)
+    unnamed = [t for t in tools if _tool_name(t) is None]
+    return [_sorted_keys(t) for t in named] + [_sorted_keys(t) for t in unnamed]
+
+
+def apply_fixes(body: dict, fixes: tuple[str, ...] | list[str]) -> tuple[dict, list[str]]:
+    """Return (body to forward, fixes that changed it). Never mutates body."""
+    applied: list[str] = []
+    out = body
+    if "canonical_tools" in fixes and isinstance(body.get("tools"), list) and body["tools"]:
+        tools = canonical_tools(body["tools"])
+        if tools != body["tools"] or json.dumps(tools) != json.dumps(body["tools"]):
+            out = {**out, "tools": tools}
+            applied.append("canonical_tools")
+    return out, applied
+
+
+def parse_fixes(spec: str | list[str] | tuple[str, ...] | None) -> tuple[str, ...]:
+    """'canonical_tools,other' or a list -> validated tuple. Unknown names raise."""
+    if not spec:
+        return ()
+    names = [s.strip() for s in (spec.split(",") if isinstance(spec, str) else spec) if s and s.strip()]
+    unknown = [n for n in names if n not in AVAILABLE_FIXES]
+    if unknown:
+        raise ValueError(f"unknown fix {unknown}; available: {', '.join(AVAILABLE_FIXES)}")
+    return tuple(dict.fromkeys(names))
+
+
+# Cause -> how to fix it. "toggle" names a proxy fix that applies it for you.
+FIX_ADVICE: dict[str, dict] = {
+    "tool_reserialize": {"toggle": "canonical_tools",
+                         "fix": "Send tools in a fixed order with deterministic serialization "
+                                "(or let the proxy do it: prefixwise serve --fix canonical_tools)."},
+    "volatile_system": {"toggle": None,
+                        "fix": "Move dates, times and ids out of the system prompt, to the end of the "
+                               "prompt or the latest user message."},
+    "tool_result_mutation": {"toggle": None,
+                             "fix": "Store each tool result once, exactly as first sent; never re-render it."},
+    "history_edit": {"toggle": None,
+                     "fix": "Append to the conversation; do not rewrite earlier messages. If you must, "
+                            "send X-Prefixwise-Compaction-Event: 1 and compact at task boundaries."},
+    "retry_replay": {"toggle": None,
+                     "fix": "Check retry logic: identical requests within seconds are re-billed in full."},
+    "breakpoint_misplaced": {"toggle": None,
+                             "fix": "Anthropic: add a cache_control breakpoint after the stable prefix "
+                                    "(tools and system)."},
+}