feat: complete Day 2 handoff with API service, PM2 process daemons, and test suites

test_multiplatform_ranking.py

@@ -764,4 +764,115 @@ def test_chartmasters_enrich_cohort_dataframe():
     # Row 1 (Non-indexed) must be None/NaN, not 0
     assert pd.isna(enriched.loc[1, "total_eas_cspc"])
     assert pd.isna(enriched.loc[1, "chartmasters_sales_rank"])
-    assert enriched.loc[1, "sales_data_status"] == "NOT_CATALOGED_YET"
+    assert enriched.loc[1, "sales_data_status"] == "NOT_CATALOGED_YET"
+# ---------------------------------------------------------------------------
+# Phase 3: Commercial Power Index (CPI) & Simulation Tests
+# ---------------------------------------------------------------------------
+
+def test_cpi_mathematical_bounds_and_null_governance():
+    """
+    Verifies that Commercial Power Index scales within [0.0, 100.0] anchored
+    to the global industry benchmarks and uncataloged artists strictly retain NaN.
+    """
+    from core.cpi_engine import CommercialPowerEngine
+
+    engine = CommercialPowerEngine()
+    df = pd.DataFrame([
+        {"name": "Eminem", "total_eas_cspc": 177_000_000},
+        {"name": "Drake", "total_eas_cspc": 142_700_000},
+        {"name": "Snoop Dogg", "total_eas_cspc": 49_500_000},
+        {"name": "Emerging Act", "total_eas_cspc": None},
+    ])
+
+    cpi = engine.calculate_cpi(df)
+
+    # Eminem (177M EAS) scales to ~95.59 on the 100k to 250M industry reference scale
+    assert cpi.iloc[0] == 95.59, f"Expected Eminem to be 95.59, got {cpi.iloc[0]}"
+    assert 85.0 < cpi.iloc[1] < cpi.iloc[0], "Drake must rank just below Eminem"
+    assert 70.0 < cpi.iloc[2] < cpi.iloc[1], "Snoop Dogg must be positive and bounded"
+    assert pd.isna(cpi.iloc[3]), "Uncataloged artist must strictly retain NaN for CPI"
+
+
+def test_cpi_simulation_weight_redistribution_fairness():
+    """
+    Verifies that simulated ranking dynamically redistributes 100% of the weight
+    back to the baseline score for uncataloged artists without synthetic dilution.
+    """
+    from core.cpi_engine import CommercialPowerEngine
+
+    engine = CommercialPowerEngine()
+    df = pd.DataFrame([
+        {"name": "Artist A (Cataloged)", "hiffi_xp_score": 80.0, "hiffi_xp_published_rank": 2, "total_eas_cspc": 100_000_000},
+        {"name": "Artist B (Uncataloged)", "hiffi_xp_score": 85.0, "hiffi_xp_published_rank": 1, "total_eas_cspc": None},
+    ])
+
+    sim = engine.simulate_composite_ranking(df, commercial_weight=0.20, mode="global_redistribution")
+
+    # Uncataloged artist must preserve baseline score without 20% penalty
+    uncataloged_score = sim.loc[sim["name"] == "Artist B (Uncataloged)", "simulated_hiffi_score"].values[0]
+    assert uncataloged_score == 85.0, f"Expected 85.0, got {uncataloged_score}"
+
+    # Cataloged artist must reflect 80% baseline + 20% CPI (100M EAS yields CPI of 88.29)
+    cataloged_score = sim.loc[sim["name"] == "Artist A (Cataloged)", "simulated_hiffi_score"].values[0]
+    expected_cpi = engine.calculate_cpi(df).iloc[0]
+    expected_cataloged = round((0.80 * 80.0) + (0.20 * expected_cpi), 2)
+    assert cataloged_score == expected_cataloged, f"Expected {expected_cataloged}, got {cataloged_score}"
+def test_cpi_simulation_rank_monotonicity():
+    """
+    Verifies that simulated ranks are strictly monotonic with respect to simulated scores.
+    """
+    from core.cpi_engine import CommercialPowerEngine
+
+    engine = CommercialPowerEngine()
+    df = pd.DataFrame([
+        {"name": "Artist A", "hiffi_xp_score": 90.0, "hiffi_xp_published_rank": 1, "total_eas_cspc": 150_000_000},
+        {"name": "Artist B", "hiffi_xp_score": 80.0, "hiffi_xp_published_rank": 2, "total_eas_cspc": 50_000_000},
+        {"name": "Artist C", "hiffi_xp_score": 70.0, "hiffi_xp_published_rank": 3, "total_eas_cspc": None},
+    ])
+
+    sim = engine.simulate_composite_ranking(df, commercial_weight=0.15, mode="global_redistribution")
+    sorted_sim = sim.sort_values(by="simulated_rank", ascending=True)
+
+    scores = sorted_sim["simulated_hiffi_score"].tolist()
+    assert scores == sorted(scores, reverse=True), "Simulated scores must decrease monotonically as simulated rank increases"
+
+
+def test_production_outputs_strictly_immutable_under_simulation():
+    """
+    CRITICAL REGRESSION TEST:
+    Verifies that running simulations across any commercial weights (0%, 10%, 20%)
+    and modes never alters or corrupts production baseline scores or published ranks.
+    """
+    from core.cpi_engine import CommercialPowerEngine
+
+    engine = CommercialPowerEngine()
+    df_master = pd.read_csv("data/hiffi_multiplatform_500.csv")
+
+    original_production_scores = df_master["hiffi_xp_score"].copy()
+    original_published_ranks = df_master["hiffi_xp_published_rank"].copy()
+
+    for mode in ["matched_only", "global_redistribution"]:
+        for weight in [0.0, 0.05, 0.15, 0.25]:
+            sim_df = engine.simulate_ranking(df_master, commercial_weight=weight, mode=mode)
+
+            pd.testing.assert_series_equal(
+                df_master["hiffi_xp_score"],
+                original_production_scores,
+                check_names=True,
+                obj="Master production scores must not mutate"
+            )
+            pd.testing.assert_series_equal(
+                df_master["hiffi_xp_published_rank"],
+                original_published_ranks,
+                check_names=True,
+                obj="Master published ranks must not mutate"
+            )
+
+            if mode == "global_redistribution":
+                unmatched_mask = df_master["sales_data_status"] == "NOT_CATALOGED_YET"
+                pd.testing.assert_series_equal(
+                    sim_df.loc[unmatched_mask, "simulated_hiffi_score"],
+                    sim_df.loc[unmatched_mask, "hiffi_xp_score"],
+                    check_names=False,
+                    obj="Uncataloged artists must retain 100% baseline score"
+                )