Merge pull request #93 from LAA-Software-Engineering/fix/timeline-severity-ordering-65

fix: order timeline effects by severity before timestamp (#65)

Author: leo-aa88

src/core/timeline/builder.py

@@ -61,16 +61,6 @@ def _classify_trigger(message: str) -> str:
     return "trigger"
 
 
-def _effect_severity(cluster: ClusterData) -> int:
-    """Lower = more severe = sorts first among effects."""
-    msg = (cluster.representative_message or "").lower()
-    if any(kw in msg for kw in ("500", "error", "fail", "exception", "refused", "denied")):
-        return 0
-    if any(kw in msg for kw in ("latency", "slow", "timeout", "degraded")):
-        return 1
-    return 2
-
-
 def _classify_secondary(cluster: ClusterData, primary: Optional[ClusterData]) -> str:
     msg = (cluster.representative_message or "").lower()
     if re.search(r"queue|pending|backlog", msg):
@@ -164,11 +154,14 @@ def build_timeline(packet: EvidencePacket) -> list[TimelineEvent]:
             services=services,
         ))
 
-    # Sort effects by: severity first, then timestamp
+    # Sort effects by: severity first, then timestamp. The category rank
+    # (error < effect < symptom) and the within-category description rank must
+    # dominate so error effects sort ahead of symptoms regardless of when each
+    # first appeared; timestamp only breaks ties among equally-severe events.
     post_events.sort(key=lambda e: (
-        e.timestamp,
         EFFECT_SEVERITY.get(e.category, 1),
         _effect_severity_from_desc(e.description),
+        e.timestamp,
     ))
 
     result = pre_events

tests/unit/test_timeline.py

@@ -0,0 +1,69 @@
+from datetime import datetime, timedelta, timezone
+
+from src.core.clustering.clusterer import ClusterData
+from src.core.explain.evidence import EvidencePacket
+from src.core.timeline.builder import build_timeline
+
+BASE = datetime(2026, 1, 1, 22, 0, 0, tzinfo=timezone.utc)
+
+
+def _cluster(message: str, offset_minutes: int, fingerprint: str = "") -> ClusterData:
+    ts = BASE + timedelta(minutes=offset_minutes)
+    return ClusterData(
+        fingerprint=fingerprint or message,
+        representative_message=message,
+        count=10,
+        services={"api": 10},
+        levels={"error": 10},
+        first_seen=ts,
+        last_seen=ts,
+        baseline_count=0,
+        change_ratio=0.0,
+        importance_score=1.0,
+    )
+
+
+def _packet(primary: ClusterData, secondary: list[ClusterData]) -> EvidencePacket:
+    return EvidencePacket(
+        window_start=BASE,
+        window_end=BASE + timedelta(hours=1),
+        total_logs=100,
+        primary_cluster=primary,
+        secondary_clusters=secondary,
+        trigger_candidates=[],
+        evidence_items=[],
+        services_affected=["api"],
+    )
+
+
+class TestTimelineOrdering:
+    def test_error_effect_sorts_before_earlier_symptom(self):
+        """Regression for #65: severity ranks before timestamp.
+
+        A 500/error effect must sort ahead of a queue-backlog symptom even
+        when the symptom appeared first — the docstring promises "error
+        effects before … symptoms last", not chronological order.
+        """
+        primary = _cluster("primary 500 error", 0)
+        symptom = _cluster("queue backlog growing", 1)   # earlier
+        effect = _cluster("checkout 500 error failed", 5)  # later, more severe
+
+        timeline = build_timeline(_packet(primary, [symptom, effect]))
+        categories = [e.category for e in timeline]
+
+        # primary error first, then the effect, then the symptom last
+        assert categories == ["error", "effect", "symptom"]
+        # the later-but-more-severe effect precedes the earlier symptom
+        eff_idx = next(i for i, e in enumerate(timeline) if "checkout" in e.description)
+        sym_idx = next(i for i, e in enumerate(timeline) if "backlog" in e.description)
+        assert eff_idx < sym_idx
+
+    def test_timestamp_breaks_ties_within_category(self):
+        """Equally-severe effects still order by timestamp."""
+        primary = _cluster("primary 500 error", 0)
+        later = _cluster("checkout 500 error late", 9)
+        earlier = _cluster("payment 500 error early", 3)
+
+        timeline = build_timeline(_packet(primary, [later, earlier]))
+        effects = [e.description for e in timeline if e.category == "effect"]
+        assert effects.index("payment 500 error early") < effects.index("checkout 500 error late")