feat(release): Phase 1-5 multi-platform pipeline, CI workflow, regression auditor, and orchestrator

test_multiplatform_ranking.py

@@ -379,25 +379,34 @@ def test_publication_eligibility_gates(dataset):
     expected_ranks = list(range(1, len(gated) + 1))
     assert ranks == expected_ranks, "Published ranks contain gaps or duplicates."
 
+
 def test_publication_gate_blocks_unverified_identity():
     """Confirms that UNCERTAIN_NEEDS_REVIEW status does not count toward evidence tiers."""
     engine = HIFFIRankingEngine()
+    now_iso = pd.Timestamp.now(tz="UTC").isoformat()
+
     test_df = pd.DataFrame([
         {
             "name": "Artist Pending Verification",
             "production_hiffi_score": 95.0,
+            "youtube_updated_at": now_iso,
             "spotify_monthly_listeners": 40_000_000,
+            "spotify_updated_at": now_iso,
             "instagram_followers": 20_000_000,
             "instagram_verification_status": "UNCERTAIN_NEEDS_REVIEW",
+            "instagram_updated_at": now_iso,
             "hiffi_xp_score": 96.0,
             "hiffi_xp_rank": 1
         },
         {
             "name": "Artist Fully Verified",
             "production_hiffi_score": 90.0,
+            "youtube_updated_at": now_iso,
             "spotify_monthly_listeners": 35_000_000,
+            "spotify_updated_at": now_iso,
             "instagram_followers": 15_000_000,
             "instagram_verification_status": "AUTOMATED_VERIFIED",
+            "instagram_updated_at": now_iso,
             "hiffi_xp_score": 91.0,
             "hiffi_xp_rank": 2
         }
@@ -414,12 +423,17 @@ def test_publication_gate_blocks_unverified_identity():
 def test_publication_gate_missing_column_fails_closed():
     """Confirms that omitting the verification column fails closed (gives 0 IG credit)."""
     engine = HIFFIRankingEngine()
+    now_iso = pd.Timestamp.now(tz="UTC").isoformat()
+
     test_df = pd.DataFrame([
         {
             "name": "Artist No Status Column",
             "production_hiffi_score": 95.0,
+            "youtube_updated_at": now_iso,
             "spotify_monthly_listeners": 40_000_000,
+            "spotify_updated_at": now_iso,
             "instagram_followers": 20_000_000,
+            "instagram_updated_at": now_iso,
             "hiffi_xp_score": 96.0,
             "hiffi_xp_rank": 1
         }
@@ -432,14 +446,18 @@ def test_publication_gate_missing_column_fails_closed():
 def test_publication_gate_zero_multiplatform_cohort():
     """Confirms an entirely Tier 1 cohort produces consecutive ranks and flags an audited shortfall."""
     engine = HIFFIRankingEngine()
+    now_iso = pd.Timestamp.now(tz="UTC").isoformat()
 
     records = [
         {
             "name": f"Solo Artist {i+1}",
             "production_hiffi_score": 85.0 - i,
+            "youtube_updated_at": now_iso,
             "spotify_monthly_listeners": np.nan,
+            "spotify_updated_at": np.nan,
             "instagram_followers": np.nan,
             "instagram_verification_status": "UNVERIFIED",
+            "instagram_updated_at": np.nan,
             "hiffi_xp_score": 80.0 - i,
             "hiffi_xp_rank": i + 1
         }
@@ -455,4 +473,123 @@ def test_publication_gate_zero_multiplatform_cohort():
     assert (gated["platform_evidence_tier"] == 1).all()
     # Shortfall must be explicitly reported
     assert audit["top_10_shortfall"] is True
-    assert audit["top_50_shortfall"] is True
+    assert audit["top_50_shortfall"] is True
+
+
+def test_freshness_gate_stale_timestamps_demote_tier():
+    """Validates that metrics older than threshold lose evidence tier credit while retaining raw score."""
+    engine = HIFFIRankingEngine()
+    ref_time = pd.Timestamp("2026-10-26T12:00:00Z")
+
+    # Artist has all metrics present, but Spotify is 10 days old (>7d) and IG is 20 days old (>14d)
+    test_df = pd.DataFrame([{
+        "name": "Artist Stale Telemetry",
+        "production_hiffi_score": 90.0,
+        "youtube_updated_at": "2026-10-25T12:00:00Z",  # 1 day old (Fresh)
+        "spotify_monthly_listeners": 25_000_000,
+        "spotify_updated_at": "2026-10-15T12:00:00Z",  # 11 days old (Stale)
+        "instagram_followers": 10_000_000,
+        "instagram_verification_status": "AUTOMATED_VERIFIED",
+        "instagram_updated_at": "2026-10-01T12:00:00Z",  # 25 days old (Stale)
+        "hiffi_xp_score": 88.5,
+        "hiffi_xp_rank": 5
+    }])
+
+    gated = engine.apply_publication_eligibility_gates(test_df, reference_time=ref_time)
+    row = gated.iloc[0]
+
+    # Only YouTube is fresh; Tier must demote to 1
+    assert row["platform_evidence_tier"] == 1
+    assert row["hiffi_xp_score"] == 88.5
+    assert "STALE_OR_MISSING_SPOTIFY_TIMESTAMP" in row["evidence_exclusions"]
+    assert "STALE_OR_MISSING_INSTAGRAM_TIMESTAMP" in row["evidence_exclusions"]
+
+
+def test_freshness_gate_missing_or_malformed_timestamp():
+    """Fails closed when timestamp string is empty, null, or malformed."""
+    engine = HIFFIRankingEngine()
+    ref_time = pd.Timestamp("2026-10-26T12:00:00Z")
+
+    test_df = pd.DataFrame([{
+        "name": "Artist Malformed Timestamp",
+        "production_hiffi_score": 85.0,
+        "youtube_updated_at": "invalid_date_format",
+        "spotify_monthly_listeners": 15_000_000,
+        "spotify_updated_at": None,
+        "instagram_followers": 5_000_000,
+        "instagram_verification_status": "AUTOMATED_VERIFIED",
+        "instagram_updated_at": "2026-10-25T12:00:00Z",  # Fresh
+        "hiffi_xp_score": 82.0,
+        "hiffi_xp_rank": 10
+    }])
+
+    gated = engine.apply_publication_eligibility_gates(test_df, reference_time=ref_time)
+    row = gated.iloc[0]
+
+    # Only Instagram is valid & fresh -> Tier 1
+    assert row["platform_evidence_tier"] == 1
+    assert "STALE_OR_MISSING_YOUTUBE_TIMESTAMP" in row["evidence_exclusions"]
+    assert "STALE_OR_MISSING_SPOTIFY_TIMESTAMP" in row["evidence_exclusions"]
+
+
+def test_freshness_gate_missing_timestamp_columns_fail_closed():
+    """Confirms that omitting timestamp columns fails closed to 0 tier credit."""
+    engine = HIFFIRankingEngine()
+
+    test_df = pd.DataFrame([{
+        "name": "Artist No Timestamps",
+        "production_hiffi_score": 90.0,
+        "spotify_monthly_listeners": 20_000_000,
+        "instagram_followers": 10_000_000,
+        "instagram_verification_status": "AUTOMATED_VERIFIED",
+        "hiffi_xp_score": 88.0,
+        "hiffi_xp_rank": 1
+    }])
+
+    gated = engine.apply_publication_eligibility_gates(test_df)
+    row = gated.iloc[0]
+
+    assert row["platform_evidence_tier"] == 0
+    assert "STALE_OR_MISSING_YOUTUBE_TIMESTAMP" in row["evidence_exclusions"]
+    assert "STALE_OR_MISSING_SPOTIFY_TIMESTAMP" in row["evidence_exclusions"]
+    assert "STALE_OR_MISSING_INSTAGRAM_TIMESTAMP" in row["evidence_exclusions"]
+
+
+def test_anomaly_detection_flags_suspicious_patterns():
+    """Validates that ratio anomalies are flagged into anomaly_flags without mutating scores."""
+    engine = HIFFIRankingEngine()
+
+    test_df = pd.DataFrame([
+        {
+            "name": "Organic Artist",
+            "lifetime_views": 100_000_000,
+            "instagram_followers": 5_000_000,
+            "spotify_monthly_listeners": 10_000_000,
+            "spotify_daily_change": 50_000,
+            "hiffi_xp_score": 85.0
+        },
+        {
+            "name": "Inorganic IG Artist",
+            "lifetime_views": 100_000,  # 100k views
+            "instagram_followers": 5_000_000,  # 5M followers (50x ratio > 10x)
+            "spotify_monthly_listeners": 500_000,
+            "spotify_daily_change": 1_000,
+            "hiffi_xp_score": 70.0
+        },
+        {
+            "name": "Spike Velocity Artist",
+            "lifetime_views": 50_000_000,
+            "instagram_followers": 1_000_000,
+            "spotify_monthly_listeners": 100_000,
+            "spotify_daily_change": 40_000,  # 40k daily change on 100k monthly (40% > 25%)
+            "hiffi_xp_score": 65.0
+        }
+    ])
+
+    flagged = engine.detect_metric_anomalies(test_df)
+
+    assert flagged.loc[0, "anomaly_flags"] == "CLEAN"
+    assert "SUSPICIOUS_IG_TO_YT_RATIO" in flagged.loc[1, "anomaly_flags"]
+    assert "EXTREME_SPOTIFY_VELOCITY_RATIO" in flagged.loc[2, "anomaly_flags"]
+    # Raw scores must remain unaffected
+    assert flagged.loc[1, "hiffi_xp_score"] == 70.0