diff --git a/contracts/epistemics/research.go b/contracts/epistemics/research.go index 59e1832..d07f4ad 100644 --- a/contracts/epistemics/research.go +++ b/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") diff --git a/dev/ACTIVE_TASK.json b/dev/ACTIVE_TASK.json index c17d818..949976c 100644 --- a/dev/ACTIVE_TASK.json +++ b/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 } diff --git a/dev/tasks/DEV-000110-citation-resolver.json b/dev/tasks/DEV-000110-citation-resolver.json new file mode 100644 index 0000000..d9d9c3a --- /dev/null +++ b/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"] +} diff --git a/tests/research_contracts/research_test.go b/tests/research_contracts/research_test.go index 030087f..d7dbf07 100644 --- a/tests/research_contracts/research_test.go +++ b/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") + } +}