feat(evidence): contribute to semantic stages (#42)

harness/tht/evidence/session.py

@@ -1,5 +1,7 @@
 """Evidence-specific projection into persisted session artifacts."""
 
+import json
+from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -56,4 +58,34 @@ def project_session(
     return list(entries.values())
 
 
-__all__ = ["project_session"]
+@dataclass(frozen=True)
+class EvidenceReceipt:
+    stage: str
+    purpose: str
+    vector_generation: str
+    evidence_ids: tuple[str, ...]
+
+    def payload(self) -> dict:
+        return {
+            "stage": self.stage,
+            "purpose": self.purpose,
+            "vector_generation": self.vector_generation,
+            "evidence_ids": list(self.evidence_ids),
+        }
+
+
+def replace_evidence_receipt(repository, session_id: str, receipt: EvidenceReceipt) -> None:
+    """Replace the one minimal receipt for a semantic stage; preserve other stages."""
+    current = repository.read_artifact(session_id, "evidence_receipts")
+    try:
+        receipts = json.loads(current) if current else []
+    except json.JSONDecodeError as error:
+        raise ValueError("Evidence receipts artifact is malformed") from error
+    if not isinstance(receipts, list):
+        raise TypeError("Evidence receipts artifact is malformed")
+    replaced = [item for item in receipts if isinstance(item, dict) and item.get("stage") != receipt.stage]
+    replaced.append(receipt.payload())
+    repository.write_artifact(session_id, "evidence_receipts", json.dumps(replaced, ensure_ascii=False, indent=2) + "\n")
+
+
+__all__ = ["EvidenceReceipt", "project_session", "replace_evidence_receipt"]