DetTrace: add replay failure similarity search

Author: kritibehl

README.md

@@ -2238,3 +2238,31 @@ Example:
     python3 regression_intelligence/build_regression_radar.py --build candidate_42 --signals retry_storm,timeout_chain,duplicate_retry_window,config_read_timeout
 
 Safe scope: heuristic replay-based build regression analysis for diagnostics review. This does not claim production release automation, CI ownership, hardware-lab testing, drivers, firmware, kernel, or real hardware emulation.
+
+---
+
+## Failure Similarity Search
+
+DetTrace includes replay failure-similarity search under `failure_similarity/`.
+
+The search compares a new trace against historical failure patterns:
+
+- timeout
+- disconnect
+- retry storm
+- state corruption
+- enumeration failure
+
+Output includes:
+
+- most similar failure family
+- similarity score
+- confidence score
+- matched evidence
+- likely root cause
+
+Example:
+
+    python3 failure_similarity/search_similar_failures.py io_transport_validation/timeout_retry_chain.json
+
+Safe scope: heuristic replay failure-similarity search for diagnostics review. This does not claim ML, production incident ranking, hardware-lab testing, drivers, firmware, kernel, or real hardware emulation.

failure_similarity/failure_patterns.json

@@ -0,0 +1,35 @@
+{
+  "safe_claim": "heuristic replay failure-similarity search; not ML or production incident ranking",
+  "patterns": [
+    {
+      "id": "timeout_pattern",
+      "family": "timeout",
+      "signals": ["timeout", "deadline_exceeded", "ack_missing", "missed_deadline"],
+      "likely_root_cause": "timeout_chain"
+    },
+    {
+      "id": "disconnect_pattern",
+      "family": "disconnect",
+      "signals": ["disconnect", "reconnect", "session_ready", "device_ready"],
+      "likely_root_cause": "reconnect_ordering_issue"
+    },
+    {
+      "id": "retry_storm_pattern",
+      "family": "retry_storm",
+      "signals": ["retry_storm", "retry_send", "duplicate_retry_window", "bounded_retry"],
+      "likely_root_cause": "unbounded_or_duplicate_retry"
+    },
+    {
+      "id": "state_corruption_pattern",
+      "family": "state_corruption",
+      "signals": ["stale_device_state", "stale_session", "state_refresh", "checksum_error"],
+      "likely_root_cause": "stale_or_corrupt_state"
+    },
+    {
+      "id": "enumeration_failure_pattern",
+      "family": "enumeration_failure",
+      "signals": ["config_read_timeout", "missing_bar_assignment", "interrupt_route_missing"],
+      "likely_root_cause": "enumeration_sequence_failure"
+    }
+  ]
+}

failure_similarity/failure_similarity_report.json

@@ -0,0 +1,36 @@
+{
+  "input_trace": "io_transport_validation/timeout_retry_chain.json",
+  "safe_claim": "heuristic replay failure-similarity search; not ML or production incident ranking",
+  "most_similar_failure": {
+    "pattern_id": "timeout_pattern",
+    "failure_family": "timeout",
+    "similarity": 0.25,
+    "confidence": 0.69,
+    "matched_evidence": [
+      "timeout"
+    ],
+    "likely_root_cause": "timeout_chain"
+  },
+  "top_matches": [
+    {
+      "pattern_id": "timeout_pattern",
+      "failure_family": "timeout",
+      "similarity": 0.25,
+      "confidence": 0.69,
+      "matched_evidence": [
+        "timeout"
+      ],
+      "likely_root_cause": "timeout_chain"
+    },
+    {
+      "pattern_id": "retry_storm_pattern",
+      "failure_family": "retry_storm",
+      "similarity": 0.25,
+      "confidence": 0.69,
+      "matched_evidence": [
+        "retry_send"
+      ],
+      "likely_root_cause": "unbounded_or_duplicate_retry"
+    }
+  ]
+}

failure_similarity/failure_similarity_report.md

@@ -0,0 +1,18 @@
+# Failure Similarity Search Report
+
+## Safe claim
+
+heuristic replay failure-similarity search; not ML or production incident ranking
+
+## Most similar failure
+
+- family: `timeout`
+- similarity: `0.25`
+- confidence: `0.69`
+- likely root cause: `timeout_chain`
+- evidence: `['timeout']`
+
+## Top matches
+
+- `timeout` similarity=`0.25` confidence=`0.69` evidence=`['timeout']` root_cause=`timeout_chain`
+- `retry_storm` similarity=`0.25` confidence=`0.69` evidence=`['retry_send']` root_cause=`unbounded_or_duplicate_retry`

failure_similarity/search_similar_failures.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+import argparse
+import json
+from pathlib import Path
+
+PATTERNS = Path("failure_similarity/failure_patterns.json")
+REPORT_JSON = Path("failure_similarity/failure_similarity_report.json")
+REPORT_MD = Path("failure_similarity/failure_similarity_report.md")
+
+
+def text_for(path):
+    return Path(path).read_text().lower()
+
+
+def score_pattern(trace_text, pattern):
+    hits = [signal for signal in pattern["signals"] if signal.lower() in trace_text]
+    score = round(len(hits) / len(pattern["signals"]), 2)
+    confidence = round(min(0.99, 0.60 + score * 0.35), 2) if hits else 0.0
+    return {
+        "pattern_id": pattern["id"],
+        "failure_family": pattern["family"],
+        "similarity": score,
+        "confidence": confidence,
+        "matched_evidence": hits,
+        "likely_root_cause": pattern["likely_root_cause"]
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Search similar DetTrace replay failure patterns")
+    parser.add_argument("trace", help="Path to trace or replay artifact")
+    args = parser.parse_args()
+
+    trace_text = text_for(args.trace)
+    patterns = json.loads(PATTERNS.read_text())["patterns"]
+
+    matches = [score_pattern(trace_text, p) for p in patterns]
+    matches = [m for m in matches if m["similarity"] > 0]
+    matches.sort(key=lambda m: (m["confidence"], m["similarity"], len(m["matched_evidence"])), reverse=True)
+
+    best = matches[0] if matches else {
+        "pattern_id": "none",
+        "failure_family": "unknown",
+        "similarity": 0.0,
+        "confidence": 0.0,
+        "matched_evidence": [],
+        "likely_root_cause": "unknown"
+    }
+
+    report = {
+        "input_trace": args.trace,
+        "safe_claim": "heuristic replay failure-similarity search; not ML or production incident ranking",
+        "most_similar_failure": best,
+        "top_matches": matches[:5]
+    }
+
+    REPORT_JSON.write_text(json.dumps(report, indent=2))
+    REPORT_MD.write_text(
+        "# Failure Similarity Search Report\n\n"
+        "## Safe claim\n\n"
+        f"{report['safe_claim']}\n\n"
+        "## Most similar failure\n\n"
+        f"- family: `{best['failure_family']}`\n"
+        f"- similarity: `{best['similarity']}`\n"
+        f"- confidence: `{best['confidence']}`\n"
+        f"- likely root cause: `{best['likely_root_cause']}`\n"
+        f"- evidence: `{best['matched_evidence']}`\n\n"
+        "## Top matches\n\n"
+        + "\n".join(
+            f"- `{m['failure_family']}` similarity=`{m['similarity']}` confidence=`{m['confidence']}` evidence=`{m['matched_evidence']}` root_cause=`{m['likely_root_cause']}`"
+            for m in report["top_matches"]
+        )
+        + "\n"
+    )
+
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    main()