evidence

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 21, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const GuidanceFacet = "contribution_guidance"

GuidanceFacet is the repository-level facet used by contribution guidance.

Variables

View Source 
var (
	ErrNotFound               = errors.New("evidence: not found")
	ErrMissingCommand         = errors.New("evidence: command argv is required")
	ErrMissingWorkspace       = errors.New("evidence: workspace path is required")
	ErrInvalidWorkspace       = errors.New("evidence: workspace path is not a directory")
	ErrInvalidEvidenceType    = errors.New("evidence: invalid evidence type")
	ErrInvalidRelation        = errors.New("evidence: invalid relation")
	ErrMissingRunKind         = errors.New("evidence: run kind is required")
	ErrInvalidComparison      = errors.New("evidence: comparison requires one base and one candidate run")
	ErrInvalidOutputLimit     = errors.New("evidence: output limit is invalid")
	ErrInvalidTimeout         = errors.New("evidence: timeout is invalid")
	ErrInvalidEnvironment     = errors.New("evidence: environment allowlist is invalid")
	ErrInvalidObservation     = errors.New("evidence: observation contract is invalid")
	ErrExecutionNotAuthorized = errors.New("evidence: host execution requires explicit authorization")
)
View Source 
var ErrSourceRevisionUnavailable = errors.New("evidence: source revision unavailable")

ErrSourceRevisionUnavailable means a reader cannot find the current local projection for a recorded source subject.

Functions

func ValidateEvidence 

func ValidateEvidence(e *Evidence) error

ValidateEvidence validates portable evidence fields without persisting them.

Types

type ComparisonClassification 

type ComparisonClassification string

ComparisonClassification is the result of comparing a base run to a candidate run. 

const (
	ComparisonFixed        ComparisonClassification = "fixed"
	ComparisonNotFixed     ComparisonClassification = "not_fixed"
	ComparisonRegression   ComparisonClassification = "regression"
	ComparisonNoDifference ComparisonClassification = "no_difference"
	ComparisonInconclusive ComparisonClassification = "inconclusive"
)

type ComparisonResult 

type ComparisonResult struct {
	Base           *ValidationRun
	Candidate      *ValidationRun
	Classification ComparisonClassification
	Explanation    string
}

ComparisonResult pairs a base and candidate run with a deterministic classification.

func Compare 

func Compare(base, candidate *ValidationRun) (*ComparisonResult, error)

Compare classifies the relationship between a base run and a candidate run. Both runs must be present and distinguishable by kind.

type Evidence 

type Evidence struct {
	ID               string
	InvestigationID  string
	HypothesisID     string
	OpportunityID    string
	ValidationRunID  string
	Type             EvidenceType
	Relation         Relation
	Description      string
	SourceRefs       []domain.SourceRef
	SourceProvenance []SourceRevision
	CreatedAt        time.Time
}

Evidence is a piece of supporting, contradicting, or inconclusive proof.

type EvidenceFilter 

type EvidenceFilter struct {
	InvestigationID string
	HypothesisID    string
	OpportunityID   string
	Relation        Relation
}

EvidenceFilter selects evidence by related identifiers or relation.

type EvidenceType 

type EvidenceType string

EvidenceType names the kind of proof being recorded. 

const (
	EvidenceTypeBaseFailingRegression      EvidenceType = "base_failing_regression"
	EvidenceTypeCandidatePassingRegression EvidenceType = "candidate_passing_regression"
	EvidenceTypeMinimalReproduction        EvidenceType = "minimal_reproduction"
	EvidenceTypeBenchmark                  EvidenceType = "benchmark"
	EvidenceTypeProfiler                   EvidenceType = "profiler"
	EvidenceTypeInvariantViolation         EvidenceType = "invariant_violation"
	EvidenceTypeCompatibilityMatrix        EvidenceType = "compatibility_matrix"
	EvidenceTypeStaticAnalysis             EvidenceType = "static_analysis"
	EvidenceTypeManualObservation          EvidenceType = "manual_observation"
	EvidenceTypeGitHubSource               EvidenceType = "github_source"
)

type ExecRunner 

type ExecRunner struct{}

ExecRunner executes commands directly, without a shell, with bounded output capture.

func NewExecRunner 

func NewExecRunner() *ExecRunner

NewExecRunner returns a shell-free Runner backed by os/exec.

func (*ExecRunner) Run 

func (r *ExecRunner) Run(ctx context.Context, req RunRequest) (*RunResult, error)

Run starts the command described by req.Args inside req.Dir. It preserves context cancellation, captures stdout and stderr up to req.MaxOutputBytes per stream, records timing, and never invokes a shell.

type ExpectedObservation added in v0.8.0 

type ExpectedObservation struct {
	Name       string
	Source     ObservationSource
	Matcher    ObservationMatcher
	Pattern    string
	Occurrence ObservationOccurrence
	Path       string
}

ExpectedObservation is one bounded assertion over captured output.

type Freshness 

type Freshness struct {
	Status FreshnessStatus
	Reason string
}

Freshness is a derived read-time assessment. It is never persisted over the evidence relation and does not imply that stale evidence is invalid.

type FreshnessEvaluator 

type FreshnessEvaluator struct {
	// contains filtered or unexported fields
}

FreshnessEvaluator compares evidence provenance with current local corpus projections. It has no network, process, or write capability.

func NewFreshnessEvaluator 

func NewFreshnessEvaluator(reader RevisionReader) *FreshnessEvaluator

NewFreshnessEvaluator returns a pure read-side freshness evaluator.

func (*FreshnessEvaluator) Evaluate 

func (e *FreshnessEvaluator) Evaluate(ctx context.Context, item *Evidence) (Freshness, error)

Evaluate derives freshness without modifying the evidence record.

type FreshnessStatus 

type FreshnessStatus string

FreshnessStatus describes whether recorded source revisions still match the winning local corpus projections. 

const (
	FreshnessFresh         FreshnessStatus = "fresh"
	FreshnessStale         FreshnessStatus = "stale"
	FreshnessUnknown       FreshnessStatus = "unknown"
	FreshnessNotApplicable FreshnessStatus = "not_applicable"
)

Freshness statuses returned by read-time evidence evaluation.

type ObservationContract added in v0.8.0 

type ObservationContract struct {
	Intent    string
	Base      []ExpectedObservation
	Candidate []ExpectedObservation
}

ObservationContract ties validation output to the intended proof.

type ObservationMatcher added in v0.8.0 

type ObservationMatcher string

ObservationMatcher selects how captured output is inspected. 

const (
	// ObservationExact performs literal substring matching.
	ObservationExact ObservationMatcher = "exact"
	// ObservationRegexp performs regular-expression matching.
	ObservationRegexp ObservationMatcher = "regexp"
)

type ObservationOccurrence added in v0.8.0 

type ObservationOccurrence string

ObservationOccurrence declares whether the matcher must be present or absent. 

const (
	// ObservationPresent requires a match.
	ObservationPresent ObservationOccurrence = "present"
	// ObservationAbsent requires no match.
	ObservationAbsent ObservationOccurrence = "absent"
)

type ObservationResult added in v0.8.0 

type ObservationResult struct {
	ExpectedObservation
	Status  ObservationStatus
	Excerpt string
	Error   string
}

ObservationResult records one assertion and a bounded matching excerpt.

type ObservationSource added in v0.8.0 

type ObservationSource string

ObservationSource selects captured command output to inspect. 

const (
	// ObservationStdout inspects captured standard output.
	ObservationStdout ObservationSource = "stdout"
	// ObservationStderr inspects captured standard error.
	ObservationStderr ObservationSource = "stderr"
	// ObservationArtifact inspects a declared workspace artifact.
	ObservationArtifact ObservationSource = "artifact"
)

type ObservationStatus added in v0.8.0 

type ObservationStatus string

ObservationStatus is the aggregate outcome of a run's output assertions. 

const (
	// ObservationNotEvaluated means no observation contract applied.
	ObservationNotEvaluated ObservationStatus = "not_evaluated"
	// ObservationMatched means every expected observation matched.
	ObservationMatched ObservationStatus = "matched"
	// ObservationMismatched means at least one observation did not match.
	ObservationMismatched ObservationStatus = "mismatched"
)

type Relation 

type Relation string

Relation describes how the evidence affects a hypothesis or opportunity. 

const (
	RelationSupporting    Relation = "supporting"
	RelationContradicting Relation = "contradicting"
	RelationInconclusive  Relation = "inconclusive"
	RelationStale         Relation = "stale"
	RelationInvalid       Relation = "invalid"
)

type Repository 

type Repository interface {
	SaveValidationDefinition(ctx context.Context, d *ValidationDefinition) error
	GetValidationDefinition(ctx context.Context, id string) (*ValidationDefinition, error)
	SaveValidationRun(ctx context.Context, r *ValidationRun) error
	GetValidationRun(ctx context.Context, id string) (*ValidationRun, error)
	SaveEvidence(ctx context.Context, e *Evidence) error
	ListEvidence(ctx context.Context, filter EvidenceFilter) ([]*Evidence, error)
}

Repository is a narrow persistence boundary for validation definitions, runs, and evidence. Concrete implementations live outside this package; production code never uses an in-memory store.

type RevisionReader 

type RevisionReader interface {
	CurrentSourceRevision(ctx context.Context, subject SourceSubject) (*SourceRevision, error)
}

RevisionReader returns the current winning revision for one stored subject, or ErrSourceRevisionUnavailable when the current projection is unavailable.

type RunClassification 

type RunClassification string

RunClassification is the high-level outcome of a single validation run. 

const (
	RunClassificationPassing   RunClassification = "passing"
	RunClassificationFailing   RunClassification = "failing"
	RunClassificationError     RunClassification = "error"
	RunClassificationCancelled RunClassification = "cancelled"
)

type RunKind 

type RunKind string

RunKind distinguishes a validation run against the base or candidate branch. 

const (
	RunKindBase      RunKind = "base"
	RunKindCandidate RunKind = "candidate"
)

type RunRequest 

type RunRequest struct {
	Args           []string
	Dir            string
	Env            []string
	MaxOutputBytes int64
}

RunRequest is a shell-free command execution request.

type RunResult 

type RunResult struct {
	ExitCode       int
	Stdout         string
	Stderr         string
	Truncated      bool
	StartedAt      time.Time
	CompletedAt    time.Time
	Error          string
	Classification RunClassification
}

RunResult is the captured output of one command execution.

type Runner 

type Runner interface {
	Run(ctx context.Context, req RunRequest) (*RunResult, error)
}

Runner executes an explicit argv inside a workspace directory without a shell.

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service manages validation definitions, runs, evidence, and base-vs-candidate comparisons.

func NewService 

func NewService(repo Repository, runner Runner) *Service

NewService returns an EvidenceService backed by repo and runner.

func (*Service) CompareValidation 

func (s *Service) CompareValidation(ctx context.Context, baseRunID, candidateRunID string) (*ComparisonResult, error)

CompareValidation loads two runs and classifies their relationship.

func (*Service) CreateEvidence 

func (s *Service) CreateEvidence(ctx context.Context, e *Evidence) error

CreateEvidence validates and stores an evidence item.

func (*Service) DefineValidation 

func (s *Service) DefineValidation(ctx context.Context, d *ValidationDefinition) error

DefineValidation validates and stores a validation definition.

func (*Service) ListEvidence 

func (s *Service) ListEvidence(ctx context.Context, filter EvidenceFilter) ([]*Evidence, error)

ListEvidence returns stored evidence matching the filter.

func (*Service) RunValidation 

func (s *Service) RunValidation(ctx context.Context, defID string, kind RunKind) (*ValidationRun, error)

RunValidation executes the definition and records a bounded run.

type SourceRevision 

type SourceRevision struct {
	Subject             SourceSubject `json:"subject"`
	SourceUpdatedAt     time.Time     `json:"source_updated_at,omitempty"`
	ObservationSequence int64         `json:"observation_sequence"`
	ObservedAt          time.Time     `json:"observed_at"`
}

SourceRevision records the exact winning source order used by evidence.

func NormalizeSourceRevisions 

func NormalizeSourceRevisions(revisions []SourceRevision) ([]SourceRevision, error)

NormalizeSourceRevisions validates, de-duplicates, and deterministically orders source provenance without changing the caller's slice.

func (SourceRevision) Validate 

func (r SourceRevision) Validate() error

Validate checks that a source revision is traceable and ordered.

type SourceSubject 

type SourceSubject struct {
	Kind       SourceSubjectKind `json:"kind"`
	Owner      string            `json:"owner"`
	Repo       string            `json:"repo"`
	ThreadKind string            `json:"thread_kind,omitempty"`
	Number     int               `json:"number,omitempty"`
	Facet      string            `json:"facet,omitempty"`
}

SourceSubject is a vendor-neutral identity for a repository, thread, or independently refreshed facet.

func (SourceSubject) Key 

func (s SourceSubject) Key() string

Key returns a stable case-insensitive subject identity.

func (SourceSubject) String 

func (s SourceSubject) String() string

func (SourceSubject) Validate 

func (s SourceSubject) Validate() error

Validate checks the shape required by each subject kind.

type SourceSubjectKind 

type SourceSubjectKind string

SourceSubjectKind identifies the independent corpus projection whose revision an evidence record used. 

const (
	SourceSubjectRepository SourceSubjectKind = "repository"
	SourceSubjectThread     SourceSubjectKind = "thread"
	SourceSubjectFacet      SourceSubjectKind = "facet"
	SourceSubjectGuidance   SourceSubjectKind = "guidance"
)

Source subject kinds supported by evidence provenance.

type ValidationDefinition 

type ValidationDefinition struct {
	ID              string
	InvestigationID string
	HypothesisID    string
	OpportunityID   string
	Name            string
	Kind            string
	Command         []string
	WorkingDir      string
	BaseWorkingDir  string
	CandidateDir    string
	Env             []string // variable names allowed through from the host environment
	Timeout         time.Duration
	MaxOutputBytes  int64
	Observation     *ObservationContract
	CreatedAt       time.Time
}

ValidationDefinition captures an explicit validation command and its workspace.

type ValidationRun 

type ValidationRun struct {
	ID                string
	DefinitionID      string
	InvestigationID   string
	HypothesisID      string
	OpportunityID     string
	Kind              RunKind
	StartedAt         time.Time
	CompletedAt       time.Time
	ExitCode          int
	Stdout            string
	Stderr            string
	Truncated         bool
	Error             string
	Classification    RunClassification
	ObservationStatus ObservationStatus
	Observations      []ObservationResult
}

ValidationRun records the outcome of one execution of a validation definition.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.