Add deterministic citation resolver

contracts/epistemics/research.go

@@ -5,6 +5,8 @@ import (
 	"strings"
 )
 
+var ErrCitationEvidenceMismatch = errors.New("citation evidence does not match source chain")
+
 type ResearchPlanID string
 type SourceID string
 type SourceSnapshotID string
@@ -70,6 +72,16 @@ type Citation struct {
 	ResolvedAtUnixMillis 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) {
+	if source.ID == "" || strings.TrimSpace(source.Locator) == "" || snapshot.SourceID != source.ID || excerpt.SnapshotID != snapshot.ID || excerpt.Validate() != nil || resolvedAtUnixMillis < 1 || evidence == "" || coverage == "" || conflict == "" {
+		return Citation{}, ErrCitationEvidenceMismatch
+	}
+	citation := Citation{ID: CitationID("citation:" + string(excerpt.ID)), ExcerptID: excerpt.ID, Evidence: evidence, Coverage: coverage, Conflict: conflict, ResolvedAtUnixMillis: resolvedAtUnixMillis}
+	return citation, citation.Validate()
+}
+
 func (p ResearchPlan) Validate() error {
 	if p.ID == "" || strings.TrimSpace(p.Question) == "" || len(p.SourceClasses) == 0 || strings.TrimSpace(p.FreshnessPolicy) == "" {
 		return errors.New("research plan requires question, source classes and freshness policy")

dev/ACTIVE_TASK.json

@@ -1,5 +1,5 @@
 {
-  "task_file": "dev/tasks/DEV-000109-research-citation-contracts.json",
-  "task_id": "DEV-000109",
+  "task_file": "dev/tasks/DEV-000110-citation-resolver.json",
+  "task_id": "DEV-000110",
   "task_revision": 1
 }

dev/tasks/DEV-000110-citation-resolver.json

@@ -0,0 +1,23 @@
+{
+  "task_id": "DEV-000110",
+  "task_revision": 1,
+  "architecture_revision": "ADR-0018",
+  "base_repo_revision": "dc7f7b3",
+  "risk_tier": "E",
+  "intent": "Add a deterministic citation resolver that requires a matching source, immutable snapshot and exact excerpt before producing citation evidence.",
+  "requirement_ids": ["WP-102", "Citation resolver", "No fabricated excerpts"],
+  "allowed_change_scope": {"modules": ["epistemics-research-contracts"], "paths": ["contracts/epistemics/**", "tests/research_contracts/**", "dev/ACTIVE_TASK.json", "dev/tasks/DEV-000110-citation-resolver.json"]},
+  "forbidden_change_scope": {"paths": ["architecture/**", "database/**", "migrations/**", "deploy/**", "security/**", "modules/**", "cmd/**", "runtime/**", "adapters/**", ".gitea/**"]},
+  "allowed_architecture_delta": {"new_cross_module_dependencies": 0, "new_canonical_owners": 0, "new_privileges": 0, "new_third_party_dependencies": 0, "new_database_owner_roles": 0},
+  "contracts": {"consume": ["DEV-000109 research/citation contracts", "Epistemics source snapshot and excerpt types"], "may_change": ["Citation resolution helper"]},
+  "semantic_owner": "epistemics-research-contract",
+  "canonical_state": [],
+  "state_transitions": ["source/snapshot/excerpt evidence -> resolved citation", "mismatched evidence -> resolution error"],
+  "side_effects_and_privileges": ["Pure deterministic validation; no connector calls, persistence, external mutation or credential access"],
+  "persistence_and_migrations": ["No schema or migration changes"],
+  "failure_retry_restart": ["Resolution is repeatable; failed resolution produces no citation"],
+  "assumptions": ["Source snapshots are immutable identifiers", "Exact excerpt offsets and text are supplied by a connector later", "Unknown/stale/conflicted evidence stays visible"],
+  "acceptance_scenarios": ["Matching source chain resolves", "Wrong source/snapshot/excerpt is rejected", "Invalid offsets are rejected", "Citation preserves stale/conflict/assumed state", "No fabricated excerpt can resolve"],
+  "required_tests": ["go test ./...", "go vet ./...", "go run ./cmd/devctl preflight -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-diff -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-architecture", "go run ./cmd/devctl/independent", "git diff --check", "citation resolver tests"],
+  "terminal_gap_states": ["BLOCKED_BY_ARCHITECTURE_GAP", "BLOCKED_BY_SPEC_GAP", "BLOCKED_BY_CONFLICT"]
+}

tests/research_contracts/research_test.go

@@ -35,3 +35,18 @@ func TestResearchContractsPreserveUnknownAndAssumedStates(t *testing.T) {
 		t.Fatal(err)
 	}
 }
+
+func TestResolveCitationRequiresMatchingSourceChain(t *testing.T) {
+	source := epistemics.Source{ID: "source-1", Locator: "https://example.test/report"}
+	snapshot := epistemics.SourceSnapshot{ID: "snapshot-1", SourceID: source.ID, ContentDigest: "sha256:abc", CapturedAtUnixMillis: 1, Freshness: epistemics.FreshnessStale}
+	excerpt := epistemics.SourceExcerpt{ID: "excerpt-1", SnapshotID: snapshot.ID, Text: "exact evidence", Start: 0, End: 14}
+	citation, err := epistemics.ResolveCitation(source, snapshot, excerpt, epistemics.EvidenceObserved, epistemics.CoveragePartial, epistemics.ConflictPresent, 2)
+	if err != nil || citation.ExcerptID != excerpt.ID || citation.Conflict != epistemics.ConflictPresent {
+		t.Fatalf("unexpected citation: %#v %v", citation, err)
+	}
+	wrong := snapshot
+	wrong.SourceID = "other-source"
+	if _, err := epistemics.ResolveCitation(source, wrong, excerpt, epistemics.EvidenceObserved, epistemics.CoverageComplete, epistemics.ConflictNone, 2); err == nil {
+		t.Fatal("expected source-chain mismatch")
+	}
+}