feat(epistemics): evaluate read-only research evidence

contracts/epistemics/research.go

@@ -16,19 +16,24 @@ type FreshnessState string
 type CoverageState string
 type ConflictState string
 type EvidenceKind string
+type ResearchFindingState string
 
 const (
-	FreshnessCurrent FreshnessState = "CURRENT"
-	FreshnessStale   FreshnessState = "STALE"
-	FreshnessUnknown FreshnessState = "UNKNOWN"
-	CoverageComplete CoverageState  = "COMPLETE"
-	CoveragePartial  CoverageState  = "PARTIAL"
-	CoverageUnknown  CoverageState  = "UNKNOWN"
-	ConflictNone     ConflictState  = "NONE"
-	ConflictPresent  ConflictState  = "PRESENT"
-	ConflictUnknown  ConflictState  = "UNKNOWN"
-	EvidenceObserved EvidenceKind   = "OBSERVED"
-	EvidenceAssumed  EvidenceKind   = "ASSUMED"
+	FreshnessCurrent  FreshnessState       = "CURRENT"
+	FreshnessStale    FreshnessState       = "STALE"
+	FreshnessUnknown  FreshnessState       = "UNKNOWN"
+	CoverageComplete  CoverageState        = "COMPLETE"
+	CoveragePartial   CoverageState        = "PARTIAL"
+	CoverageUnknown   CoverageState        = "UNKNOWN"
+	ConflictNone      ConflictState        = "NONE"
+	ConflictPresent   ConflictState        = "PRESENT"
+	ConflictUnknown   ConflictState        = "UNKNOWN"
+	EvidenceObserved  EvidenceKind         = "OBSERVED"
+	EvidenceAssumed   EvidenceKind         = "ASSUMED"
+	FindingSupported  ResearchFindingState = "SUPPORTED"
+	FindingStale      ResearchFindingState = "STALE"
+	FindingConflicted ResearchFindingState = "CONFLICTED"
+	FindingUnknown    ResearchFindingState = "UNKNOWN"
 )
 
 type ResearchPlan struct {
@@ -72,6 +77,35 @@ type Citation struct {
 	ResolvedAtUnixMillis int64
 }
 
+// ResearchCandidate is read-only evidence returned by a connector. The
+// connector supplies the immutable snapshot and exact excerpt; the evaluator
+// never fetches, rewrites or invents either one.
+type ResearchCandidate struct {
+	PropositionKey string
+	Statement      string
+	Source         Source
+	Snapshot       SourceSnapshot
+	Excerpt        SourceExcerpt
+	Evidence       EvidenceKind
+	Coverage       CoverageState
+	Conflict       ConflictState
+}
+
+type ResearchFinding struct {
+	PropositionKey string
+	Statement      string
+	Claim          Claim
+	Citations      []Citation
+	State          ResearchFindingState
+	Reason         string
+}
+
+type ResearchResult struct {
+	PlanID                ResearchPlanID
+	Findings              []ResearchFinding
+	EvaluatedAtUnixMillis int64
+}
+
 // ResolveCitation creates evidence only when all identifiers form one exact
 // source chain. It deliberately does not fetch, infer or rewrite source text.
 func ResolveCitation(source Source, snapshot SourceSnapshot, excerpt SourceExcerpt, evidence EvidenceKind, coverage CoverageState, conflict ConflictState, resolvedAtUnixMillis int64) (Citation, error) {