evidence

package
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const ExternalReceiptSchemaV1 = "gitcontribute.external-validation.v1"
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 DigestExternalReceipt added in v0.14.0 

func DigestExternalReceipt(receipt ExternalReceipt) (string, error)

DigestExternalReceipt returns the stable receipt content identity.

func ValidateEvidence 

func ValidateEvidence(e *Evidence) error

ValidateEvidence validates portable evidence fields without persisting them.

Types

type CleanupResult added in v0.10.0 

type CleanupResult struct {
	Status    string
	Reason    string
	Survivors []ProcessIdentity
	CheckedAt time.Time
}

CleanupResult records whether sampled descendants survived the shutdown boundary. Survivors are matched by PID and creation time.

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
	ValidationRun        *ValidationRun
	ValidationDefinition *ValidationDefinition
}

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 ExternalReceipt added in v0.14.0 

type ExternalReceipt struct {
	SchemaVersion   string            `json:"schema_version"`
	Producer        string            `json:"producer"`
	ReceiptSHA256   string            `json:"receipt_sha256"`
	ValidationID    string            `json:"validation_id"`
	InvestigationID string            `json:"investigation_id"`
	OpportunityID   string            `json:"opportunity_id,omitempty"`
	Kind            RunKind           `json:"kind"`
	Repository      string            `json:"repository,omitempty"`
	Revision        string            `json:"revision,omitempty"`
	ArtifactSHA256  string            `json:"artifact_sha256,omitempty"`
	Provider        string            `json:"provider,omitempty"`
	ExternalRunID   string            `json:"external_run_id,omitempty"`
	Command         []string          `json:"argv,omitempty"`
	WorkingDir      string            `json:"working_dir,omitempty"`
	Environment     map[string]string `json:"environment,omitempty"`
	Artifacts       map[string]string `json:"artifacts,omitempty"`
	StartedAt       time.Time         `json:"started_at"`
	CompletedAt     time.Time         `json:"completed_at"`
	ExitCode        int               `json:"exit_code"`
	Classification  RunClassification `json:"classification"`
	Stdout          string            `json:"stdout,omitempty"`
	Stderr          string            `json:"stderr,omitempty"`
	Truncated       bool              `json:"truncated,omitempty"`
	Limitations     []string          `json:"limitations,omitempty"`
	Incomplete      bool              `json:"incomplete,omitempty"`
}

ExternalReceipt is a producer-neutral, bounded execution record. Digest is the SHA-256 of the JSON encoding of this structure with ReceiptSHA256 empty.

type ExternalReceiptProvenance added in v0.14.0 

type ExternalReceiptProvenance struct {
	SchemaVersion  string
	Producer       string
	ValidationID   string
	ReceiptSHA256  string
	Repository     string
	Revision       string
	ArtifactSHA256 string
	Provider       string
	ExternalRunID  string
	Command        []string
	WorkingDir     string
	Environment    map[string]string
	Artifacts      map[string]string
	Limitations    []string
	Incomplete     bool
}

ExternalReceiptProvenance preserves the trust and source boundary of a validation observation produced outside GitContribute.

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 Int64Metric added in v0.10.0 

type Int64Metric struct {
	Value             *int64
	UnavailableReason string
}

Int64Metric represents a sampled value. Nil means unavailable, never zero.

type MCPStdioRunner added in v0.10.0 

type MCPStdioRunner struct{}

MCPStdioRunner uses the official MCP SDK to measure declared protocol milestones. It does not parse or infer protocol state from process output.

func NewMCPStdioRunner added in v0.10.0 

func NewMCPStdioRunner() *MCPStdioRunner

NewMCPStdioRunner returns an SDK-backed stdio validation runner.

func (*MCPStdioRunner) Run added in v0.10.0 

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

Run starts an MCP stdio server, initializes a client session, lists tools, and closes the session while recording each protocol boundary.

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 ProcessIdentity added in v0.10.0 

type ProcessIdentity struct {
	PID                 int32
	CreateTimeUnixMilli int64
}

ProcessIdentity prevents PID reuse from merging unrelated process samples.

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 RepeatValidationOptions added in v0.10.0 

type RepeatValidationOptions struct {
	Kinds          []RunKind
	RunCount       int
	Concurrency    int
	PerRunTimeout  time.Duration
	OverallTimeout time.Duration
	SampleInterval time.Duration
}

RepeatValidationOptions bounds one repeat/stress request.

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)
	SaveValidationRunGroup(ctx context.Context, group *ValidationRunGroup) error
	GetValidationRunGroup(ctx context.Context, id string) (*ValidationRunGroup, 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 ResourceTelemetry added in v0.10.0 

type ResourceTelemetry struct {
	Provider                   string
	Platform                   string
	SampleInterval             time.Duration
	SampleCount                int
	CPUTimeMillis              Int64Metric
	PeakRSSBytes               Uint64Metric
	PeakChildCount             Int64Metric
	SamplerOverheadNanoseconds int64
}

ResourceTelemetry contains bounded process-tree high-water marks.

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 RunGroupClassification added in v0.10.0 

type RunGroupClassification string

RunGroupClassification summarizes repeated, semantically comparable runs. 

const (
	// RunGroupStablePass means every comparable attempt passed.
	RunGroupStablePass RunGroupClassification = "stable_pass"
	// RunGroupStableFail means every comparable attempt failed.
	RunGroupStableFail RunGroupClassification = "stable_fail"
	// RunGroupFlaky means comparable attempts disagreed.
	RunGroupFlaky RunGroupClassification = "flaky"
	// RunGroupInconclusive means attempts could not support a semantic conclusion.
	RunGroupInconclusive RunGroupClassification = "inconclusive"
	// RunGroupCancelled means the requested sample was not completed.
	RunGroupCancelled RunGroupClassification = "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 RunPhases added in v0.10.0 

type RunPhases struct {
	SpawnStartedAt    time.Time
	ProcessStartedAt  time.Time
	InitializedAt     time.Time
	ToolsListedAt     time.Time
	FirstResponseAt   time.Time
	ExecutionEndedAt  time.Time
	ShutdownStartedAt time.Time
	ShutdownCheckedAt time.Time
}

RunPhases records generic process boundaries. Protocol readiness milestones require a declared adapter and are never inferred from command output.

type RunRequest 

type RunRequest struct {
	Args             []string
	Dir              string
	Env              []string
	MaxOutputBytes   int64
	SampleInterval   time.Duration
	ReadinessTimeout time.Duration
}

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
	Process        ProcessIdentity
	Phases         RunPhases
	TimeoutPhase   string
	FailurePhase   string
	Resources      ResourceTelemetry
	Cleanup        CleanupResult
}

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) AttachExternalReceipt added in v0.14.0 

func (s *Service) AttachExternalReceipt(ctx context.Context, receipt ExternalReceipt) (*ValidationRun, error)

AttachExternalReceipt validates and stores an external observation without executing any command or contacting its producer.

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.

func (*Service) RunValidationGroup added in v0.10.0 

func (s *Service) RunValidationGroup(ctx context.Context, defID string, opts RepeatValidationOptions) (*ValidationRunGroup, error)

RunValidationGroup executes independently timed attempts, persists every successful run record, and then persists one bounded aggregate.

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 Uint64Metric added in v0.10.0 

type Uint64Metric struct {
	Value             *uint64
	UnavailableReason string
}

Uint64Metric represents a sampled unsigned value.

type ValidationAggregate added in v0.10.0 

type ValidationAggregate struct {
	Kind                   RunKind
	Requested              int
	Completed              int
	Passing                int
	Failing                int
	Inconclusive           int
	Cancelled              int
	Classification         RunGroupClassification
	ResourceClassification string
}

ValidationAggregate preserves semantic and resource conclusions separately.

type ValidationAttempt added in v0.10.0 

type ValidationAttempt struct {
	Index             int
	Kind              RunKind
	RunID             string
	StartedAt         time.Time
	CompletedAt       time.Time
	ExitCode          int
	Classification    RunClassification
	ObservationStatus ObservationStatus
	TimeoutPhase      string
	FailurePhase      string
	Error             string
	Process           ProcessIdentity
	Phases            RunPhases
	Resources         ResourceTelemetry
	Cleanup           CleanupResult
}

ValidationAttempt is a bounded summary of one independently timed run. Full bounded output remains in the referenced ValidationRun record.

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
	WorkspaceID          string
	BaseWorkspaceID      string
	CandidateWorkspaceID string
	Env                  []string // variable names allowed through from the host environment
	Timeout              time.Duration
	MaxOutputBytes       int64
	Observation          *ObservationContract
	Protocol             ValidationProtocol
	ReadinessTimeout     time.Duration
	CreatedAt            time.Time
}

ValidationDefinition captures an explicit validation command and its workspace.

type ValidationGroupComparison added in v0.10.0 

type ValidationGroupComparison struct {
	Classification ComparisonClassification
	Explanation    string
}

ValidationGroupComparison compares stable base and candidate aggregates.

type ValidationProtocol added in v0.10.0 

type ValidationProtocol string

ValidationProtocol selects an explicit structured adapter. Empty means the generic command runner; protocol milestones are never inferred from stdout. 

const (
	// ValidationProtocolMCPStdio measures initialize and tools/list through the official MCP SDK.
	ValidationProtocolMCPStdio ValidationProtocol = "mcp_stdio"
)

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
	WorkspaceSnapshotBefore string
	WorkspaceSnapshotAfter  string
	WorkspaceBindingStatus  string
	WorkspaceBindingReason  string
	Process                 ProcessIdentity
	Phases                  RunPhases
	TimeoutPhase            string
	FailurePhase            string
	Resources               ResourceTelemetry
	Cleanup                 CleanupResult
	ExecutionOrigin         string
	External                *ExternalReceiptProvenance
}

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

type ValidationRunGroup added in v0.10.0 

type ValidationRunGroup struct {
	ID                  string
	DefinitionID        string
	InvestigationID     string
	HypothesisID        string
	OpportunityID       string
	ConfigurationSHA256 string
	RequestedRuns       int
	CompletedRuns       int
	Concurrency         int
	PerRunTimeout       time.Duration
	OverallTimeout      time.Duration
	SampleInterval      time.Duration
	Attempts            []ValidationAttempt
	Aggregates          []ValidationAggregate
	Classification      RunGroupClassification
	Comparison          *ValidationGroupComparison
	StartedAt           time.Time
	CompletedAt         time.Time
}

ValidationRunGroup is one persisted bounded repeat/stress execution.

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.