Consume governed recipients and add operational checks

src/govoplan_campaign/backend/schemas.py

@@ -378,6 +378,7 @@ class CampaignRecipientAddressSourceSnapshotRequest(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     source_id: str = Field(min_length=1)
+    purpose: str = Field(default="campaign_delivery", min_length=1, max_length=120)
 
 
 class CampaignRecipientSnapshotItem(BaseModel):
@@ -389,6 +390,18 @@ class CampaignRecipientSnapshotItem(BaseModel):
     provenance: dict[str, Any] = Field(default_factory=dict)
 
 
+class CampaignRecipientSnapshotExcludedItem(BaseModel):
+    contact_id: str
+    display_name: str
+    channel: str
+    target: str
+    contact_point_id: str | None = None
+    status: str
+    reason_code: str | None = None
+    explanation: str | None = None
+    provenance: dict[str, Any] = Field(default_factory=dict)
+
+
 class CampaignRecipientAddressSourceSnapshotResponse(BaseModel):
     source_id: str
     source_label: str
@@ -396,6 +409,10 @@ class CampaignRecipientAddressSourceSnapshotResponse(BaseModel):
     source_revision: str
     generated_at: str
     recipients: list[CampaignRecipientSnapshotItem] = Field(default_factory=list)
+    excluded: list[CampaignRecipientSnapshotExcludedItem] = Field(default_factory=list)
+    included_count: int = 0
+    excluded_count: int = 0
+    purpose: str = "campaign_delivery"
     provenance: dict[str, Any] = Field(default_factory=dict)