feat(scouts): add SourceConnector protocol and item types

tests/test_scout_connectors_base.py

@@ -0,0 +1,48 @@
+"""Tests for the SourceConnector base protocol and shared types."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import pytest
+
+from app.scouts.connectors.base import (
+    ItemContent,
+    ItemMetadata,
+    ItemRef,
+    TriageVerdict,
+)
+
+
+def test_item_ref_round_trips_through_pydantic():
+    ref = ItemRef(source_msg_ref="abc123", received_at=datetime.now(tz=timezone.utc))
+    parsed = ItemRef.model_validate(ref.model_dump())
+    assert parsed.source_msg_ref == "abc123"
+    assert parsed.received_at == ref.received_at
+
+
+def test_item_metadata_allows_all_optional():
+    meta = ItemMetadata()
+    assert meta.subject is None
+    assert meta.sender is None
+    assert meta.snippet is None
+    assert meta.received_at is None
+
+
+def test_item_content_requires_metadata_and_body():
+    content = ItemContent(
+        metadata=ItemMetadata(subject="hi"),
+        body_text="hello world",
+        raw_headers={"X-Foo": "bar"},
+    )
+    assert content.metadata.subject == "hi"
+    assert content.body_text == "hello world"
+    assert content.raw_headers["X-Foo"] == "bar"
+
+
+def test_triage_verdict_constraints():
+    v = TriageVerdict(verdict="relevant", reason="contains task language", confidence=0.92)
+    assert v.verdict == "relevant"
+
+    with pytest.raises(ValueError):
+        TriageVerdict(verdict="meh", reason="x", confidence=0.5)  # bad enum value