feat: add versioned artifact metadata

Co-Authored-By: Codex <noreply@openai.com>

Author: Pigbibi

src/research_signal_context_pipelines/schema.py

@@ -28,6 +28,7 @@ class SignalValidationError(ValueError):
 ALLOWED_REGIMES = frozenset({"risk_on", "risk_off", "neutral", "mixed", "unknown"})
 ALLOWED_BIAS_VALUES = frozenset({"positive", "negative", "neutral", "watch", "avoid"})
 REQUIRED_SIGNAL_HORIZON = "1-3 years"
+SUPPORTED_SCHEMA_VERSIONS = frozenset({"1", "2"})
 
 
 def _require_mapping(value: Any, name: str) -> Mapping[str, Any]:
@@ -82,11 +83,15 @@ def validate_signal(payload: Mapping[str, Any]) -> None:
     if missing:
         raise SignalValidationError(f"missing required keys: {', '.join(missing)}")
 
-    if _require_string(payload["schema_version"], "schema_version") != "1":
-        raise SignalValidationError("schema_version must be '1'")
+    schema_version = _require_string(payload["schema_version"], "schema_version")
+    if schema_version not in SUPPORTED_SCHEMA_VERSIONS:
+        raise SignalValidationError("schema_version must be '1' or '2'")
     _require_iso_date(payload["as_of"], "as_of")
     _require_iso_datetime(payload["generated_at"], "generated_at")
     _require_iso_date(payload["expires_at"], "expires_at")
+    if schema_version == "2":
+        _require_string(payload.get("model_version"), "model_version")
+        _require_string(payload.get("scoring_version"), "scoring_version")
 
     if payload["mode"] != "shadow":
         raise SignalValidationError("mode must be 'shadow'")

src/research_signal_context_pipelines/theme_momentum.py

@@ -25,6 +25,9 @@
 THEME_MOMENTUM_HORIZON = "medium"
 THEME_MOMENTUM_HORIZON_WINDOW = "2-12 weeks"
 THEME_MOMENTUM_HORIZON_WINDOW_ZH = "2-12周"
+THEME_MOMENTUM_MODEL_VERSION = "theme-momentum-v1"
+THEME_MOMENTUM_SCORING_VERSION = "theme-momentum-rules-v1"
+THEME_MOMENTUM_EXPIRY_DAYS = 84
 
 
 def utc_now_iso() -> str:
@@ -218,9 +221,12 @@ def build_theme_momentum_snapshot(
 
     taxonomy_versions = sorted({theme.taxonomy_version for theme in themes.values() if theme.taxonomy_version})
     return {
-        "schema_version": "1",
+        "schema_version": "2",
         "as_of": snapshot_as_of,
         "generated_at": (generated_at or dt.datetime.now(dt.UTC)).isoformat().replace("+00:00", "Z"),
+        "expires_at": (parse_price_date(snapshot_as_of) + dt.timedelta(days=THEME_MOMENTUM_EXPIRY_DAYS)).isoformat(),
+        "model_version": THEME_MOMENTUM_MODEL_VERSION,
+        "scoring_version": THEME_MOMENTUM_SCORING_VERSION,
         "mode": "theme_momentum_snapshot",
         "artifact_type": THEME_MOMENTUM_ARTIFACT_TYPE,
         "horizon": THEME_MOMENTUM_HORIZON,

tests/test_signal_validation.py

@@ -21,6 +21,33 @@ def test_example_signal_is_valid() -> None:
     assert payload["horizon"] == "1-3 years"
 
 
+def test_v2_signal_requires_versioned_model_metadata() -> None:
+    payload = load_example()
+    payload.update(
+        {
+            "schema_version": "2",
+            "model_version": "shadow-v2",
+            "scoring_version": "rules-v2",
+        }
+    )
+
+    validate_signal(payload)
+
+
+def test_v1_signal_remains_readable_without_v2_metadata() -> None:
+    payload = load_example()
+
+    validate_signal(payload)
+
+
+def test_v2_signal_requires_model_and_scoring_versions() -> None:
+    payload = load_example()
+    payload["schema_version"] = "2"
+
+    with pytest.raises(SignalValidationError, match="model_version"):
+        validate_signal(payload)
+
+
 def test_signal_requires_long_horizon_contract() -> None:
     payload = load_example()
     payload["horizon"] = "1-3 months"

tests/test_theme_momentum.py

@@ -58,6 +58,10 @@ def test_theme_momentum_ranks_strong_broad_theme_first() -> None:
 
     ranked = snapshot["theme_ranks"]
     assert snapshot["artifact_type"] == "medium_horizon_theme_context"
+    assert snapshot["schema_version"] == "2"
+    assert snapshot["expires_at"] == "2025-12-30"
+    assert snapshot["model_version"] == "theme-momentum-v1"
+    assert snapshot["scoring_version"] == "theme-momentum-rules-v1"
     assert snapshot["horizon"] == "medium"
     assert snapshot["horizon_window"] == "2-12 weeks"
     assert snapshot["horizon_window_label"] == "2-12周"