Add research citation evidence contracts
This commit is contained in:
@@ -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
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
|
||||
@@ -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"]
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user