feat: add phase1 alpha operator contract

tests/test_alpha_factors.py

@@ -8,6 +8,7 @@ import pytest
 
 from quant_engine.alpha_factors import (
     ALPHA158_REGISTRY,
+    ALPHA158_PHASE1_OPERATOR_SPECS,
     alpha_001,
     alpha_002,
     alpha_003,
@@ -166,6 +167,8 @@ from quant_engine.alpha_factors import (
     alpha_156,
     alpha_157,
     alpha_158,
+    evaluate_phase1_operator,
+    list_phase1_operators,
     correlation,
     covariance,
     decay_linear,
@@ -1232,3 +1235,89 @@ def test_parse_alpha_formula_round_trip_jsonb():
     serialized = json.dumps(parsed)
     assert isinstance(serialized, str)
     assert "ts_rank" in serialized
+
+
+# ── v1.2.0 Phase 1: deterministic operator dispatch contract ──────────────
+
+
+def test_phase1_operator_catalog_is_explicit_and_serializable():
+    """Phase 1 exposes a stable, JSON-friendly catalog for downstream callers."""
+    import json
+
+    expected = {
+        "rank",
+        "delta",
+        "ts_mean",
+        "ts_std",
+        "ts_rank",
+        "correlation",
+        "ts_min",
+        "ts_max",
+        "ts_sum",
+        "decay_linear",
+    }
+    assert set(list_phase1_operators()) == expected
+    assert set(ALPHA158_PHASE1_OPERATOR_SPECS) == expected
+    json.dumps(ALPHA158_PHASE1_OPERATOR_SPECS)
+    for name, spec in ALPHA158_PHASE1_OPERATOR_SPECS.items():
+        assert spec["name"] == name
+        assert isinstance(spec["inputs"], list)
+        assert isinstance(spec["formula"], str)
+
+
+def test_phase1_unary_operators_preserve_index_and_are_deterministic():
+    values = pd.Series([1.0, 2.0, 3.0, 4.0], index=["a", "b", "c", "d"])
+
+    first = evaluate_phase1_operator("rank", values)
+    second = evaluate_phase1_operator("rank", values)
+
+    pd.testing.assert_series_equal(first, second)
+    assert first.index.equals(values.index)
+    assert first.iloc[-1] == pytest.approx(1.0)
+
+
+@pytest.mark.parametrize(
+    ("name", "window"),
+    [
+        ("delta", 2),
+        ("ts_mean", 2),
+        ("ts_std", 2),
+        ("ts_rank", 2),
+        ("ts_min", 2),
+        ("ts_max", 2),
+        ("ts_sum", 2),
+        ("decay_linear", 2),
+    ],
+)
+def test_phase1_windowed_operators_require_explicit_window(name: str, window: int):
+    values = pd.Series([1.0, 2.0, 3.0, 4.0])
+
+    result = evaluate_phase1_operator(name, values, window=window)
+
+    assert result.index.equals(values.index)
+    with pytest.raises(ValueError, match="window"):
+        evaluate_phase1_operator(name, values)
+    with pytest.raises(ValueError, match="positive integer"):
+        evaluate_phase1_operator(name, values, window=1.5)  # type: ignore[arg-type]
+
+
+def test_phase1_binary_correlation_requires_aligned_secondary_input():
+    values = pd.Series([1.0, 2.0, 3.0, 4.0])
+    other = pd.Series([4.0, 3.0, 2.0, 1.0])
+
+    result = evaluate_phase1_operator("correlation", values, other, window=2)
+
+    assert result.iloc[-1] == pytest.approx(-1.0)
+    with pytest.raises(ValueError, match="secondary"):
+        evaluate_phase1_operator("correlation", values, window=2)
+
+
+def test_phase1_dispatch_rejects_unknown_or_unused_arguments():
+    values = pd.Series([1.0, 2.0, 3.0])
+
+    with pytest.raises(KeyError, match="not registered"):
+        evaluate_phase1_operator("unknown", values)
+    with pytest.raises(ValueError, match="window"):
+        evaluate_phase1_operator("rank", values, window=2)
+    with pytest.raises(ValueError, match="secondary"):
+        evaluate_phase1_operator("rank", values, values)