diff --git a/contracts/epistemics/research.go b/contracts/epistemics/research.go new file mode 100644 index 0000000..59e1832 --- /dev/null +++ b/contracts/epistemics/research.go @@ -0,0 +1,99 @@ +package epistemics + +import ( + "errors" + "strings" +) + +type ResearchPlanID string +type SourceID string +type SourceSnapshotID string +type SourceExcerptID string +type CitationID string +type FreshnessState string +type CoverageState string +type ConflictState string +type EvidenceKind 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" +) + +type ResearchPlan struct { + ID ResearchPlanID + Question string + SourceClasses []string + FreshnessPolicy string + CreatedAtUnixMillis int64 +} + +type Source struct { + ID SourceID + Kind string + Locator string + Title string + Publisher string +} + +type SourceSnapshot struct { + ID SourceSnapshotID + SourceID SourceID + ContentDigest string + CapturedAtUnixMillis int64 + Freshness FreshnessState +} + +type SourceExcerpt struct { + ID SourceExcerptID + SnapshotID SourceSnapshotID + Text string + Start int64 + End int64 +} + +type Citation struct { + ID CitationID + ExcerptID SourceExcerptID + Evidence EvidenceKind + Coverage CoverageState + Conflict ConflictState + ResolvedAtUnixMillis int64 +} + +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") + } + return nil +} + +func (s SourceSnapshot) Validate() error { + if s.ID == "" || s.SourceID == "" || strings.TrimSpace(s.ContentDigest) == "" || s.CapturedAtUnixMillis < 1 || s.Freshness == "" { + return errors.New("source snapshot requires source, digest, capture time and freshness") + } + return nil +} + +func (e SourceExcerpt) Validate() error { + if e.ID == "" || e.SnapshotID == "" || strings.TrimSpace(e.Text) == "" || e.Start < 0 || e.End < e.Start { + return errors.New("source excerpt requires snapshot, text and valid offsets") + } + return nil +} + +func (c Citation) Validate() error { + if c.ID == "" || c.ExcerptID == "" || c.Evidence == "" || c.Coverage == "" || c.Conflict == "" || c.ResolvedAtUnixMillis < 1 { + return errors.New("citation requires exact excerpt, evidence, coverage, conflict and resolution time") + } + return nil +} diff --git a/dev/ACTIVE_TASK.json b/dev/ACTIVE_TASK.json index 9a7b87a..c17d818 100644 --- a/dev/ACTIVE_TASK.json +++ b/dev/ACTIVE_TASK.json @@ -1,5 +1,5 @@ { - "task_file": "dev/tasks/DEV-000108-context-compiler-gateway-integration.json", - "task_id": "DEV-000108", + "task_file": "dev/tasks/DEV-000109-research-citation-contracts.json", + "task_id": "DEV-000109", "task_revision": 1 } diff --git a/dev/tasks/DEV-000109-research-citation-contracts.json b/dev/tasks/DEV-000109-research-citation-contracts.json new file mode 100644 index 0000000..dcafee3 --- /dev/null +++ b/dev/tasks/DEV-000109-research-citation-contracts.json @@ -0,0 +1,23 @@ +{ + "task_id": "DEV-000109", + "task_revision": 1, + "architecture_revision": "ADR-0018", + "base_repo_revision": "e3b55c9", + "risk_tier": "E", + "intent": "Add typed read-only research and citation evidence contracts for plans, source snapshots, excerpts and freshness/conflict state without connecting external sources.", + "requirement_ids": ["WP-102", "Source snapshot and citation resolver", "UNKNOWN/ASSUMPTION freshness conflict"], + "allowed_change_scope": {"modules": ["epistemics-research-contracts"], "paths": ["contracts/epistemics/**", "tests/research_contracts/**", "dev/ACTIVE_TASK.json", "dev/tasks/DEV-000109-research-citation-contracts.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": ["Proposed ADR-0019 Truth V1 evidence/provenance", "Existing Epistemics owner", "Existing Artifact typed reference boundary"], "may_change": ["Epistemics research/citation contract"]}, + "semantic_owner": "epistemics-research-contract", + "canonical_state": [], + "state_transitions": ["research plan -> source snapshot -> excerpt -> citation", "source conflict/freshness result -> explicit claim status"], + "side_effects_and_privileges": ["Typed value validation only; no connector calls, external mutation, credentials or persistence"], + "persistence_and_migrations": ["No schema or migration changes"], + "failure_retry_restart": ["Unknown source/retrieval state is retained as UNKNOWN and cannot become a citation silently"], + "assumptions": ["Connectors and durable storage arrive in later tasks", "Citation references an exact excerpt identity and snapshot", "Research output is read-only evidence"], + "acceptance_scenarios": ["Plan identifies question, source classes and freshness policy", "Snapshot has content digest and retrieval timestamp", "Citation requires exact excerpt and source snapshot", "stale/conflicted/unknown states remain explicit", "assumption is distinguishable from observed evidence"], + "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", "research contract 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 new file mode 100644 index 0000000..030087f --- /dev/null +++ b/tests/research_contracts/research_test.go @@ -0,0 +1,37 @@ +package research_contracts_test + +import ( + "testing" + + "git.cin.su/m/Assistant/contracts/epistemics" +) + +func TestResearchContractsRequireExactEvidence(t *testing.T) { + plan := epistemics.ResearchPlan{ID: "plan-1", Question: "What changed?", SourceClasses: []string{"repository"}, FreshnessPolicy: "same-day"} + if err := plan.Validate(); err != nil { + t.Fatal(err) + } + snapshot := epistemics.SourceSnapshot{ID: "snapshot-1", SourceID: "source-1", ContentDigest: "sha256:abc", CapturedAtUnixMillis: 1, Freshness: epistemics.FreshnessCurrent} + if err := snapshot.Validate(); err != nil { + t.Fatal(err) + } + excerpt := epistemics.SourceExcerpt{ID: "excerpt-1", SnapshotID: snapshot.ID, Text: "exact evidence", Start: 0, End: 14} + if err := excerpt.Validate(); err != nil { + t.Fatal(err) + } + citation := epistemics.Citation{ID: "citation-1", ExcerptID: excerpt.ID, Evidence: epistemics.EvidenceObserved, Coverage: epistemics.CoverageComplete, Conflict: epistemics.ConflictNone, ResolvedAtUnixMillis: 2} + if err := citation.Validate(); err != nil { + t.Fatal(err) + } +} + +func TestResearchContractsPreserveUnknownAndAssumedStates(t *testing.T) { + snapshot := epistemics.SourceSnapshot{ID: "snapshot-unknown", SourceID: "source-1", ContentDigest: "sha256:abc", CapturedAtUnixMillis: 1, Freshness: epistemics.FreshnessUnknown} + if err := snapshot.Validate(); err != nil { + t.Fatal(err) + } + citation := epistemics.Citation{ID: "citation-assumed", ExcerptID: "excerpt-1", Evidence: epistemics.EvidenceAssumed, Coverage: epistemics.CoveragePartial, Conflict: epistemics.ConflictPresent, ResolvedAtUnixMillis: 2} + if err := citation.Validate(); err != nil { + t.Fatal(err) + } +}