investigation

package
v0.12.0 Latest Latest
Warning

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

Go to latest
Published: Jul 25, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNotFound              = errors.New("investigation: not found")
	ErrInvalidRepo           = errors.New("investigation: invalid repository reference")
	ErrInvalidTransition     = errors.New("investigation: invalid status transition")
	ErrMissingTitle          = errors.New("investigation: title is required")
	ErrMissingProblem        = errors.New("investigation: problem statement is required")
	ErrInvalidCategory       = errors.New("investigation: invalid category")
	ErrInvalidThreadBaseline = errors.New("investigation: invalid thread baseline")
	ErrContradictingEvidence = errors.New("investigation: contradicting evidence blocks this transition")
	ErrConflict              = errors.New("investigation: record changed concurrently")
)

Functions

func ValidCategory added in v0.10.0

func ValidCategory(c Category) bool

ValidCategory reports whether c is a supported contribution category.

func ValidHypothesisTransition

func ValidHypothesisTransition(from, to HypothesisStatus) bool

ValidHypothesisTransition reports whether moving from -> to is allowed.

func ValidOpportunityTransition

func ValidOpportunityTransition(from, to OpportunityStatus) bool

ValidOpportunityTransition reports whether moving from -> to is allowed.

Types

type Category

type Category string

Category classifies the kind of hypothesis or opportunity.

const (
	CategoryBug           Category = "bug"
	CategoryPerformance   Category = "performance"
	CategoryArchitecture  Category = "architecture"
	CategoryTesting       Category = "testing"
	CategoryDocumentation Category = "documentation"
	CategoryMaintenance   Category = "maintenance"
	CategoryCompatibility Category = "compatibility"
	CategorySecurity      Category = "security"
	CategoryOther         Category = "other"
)

type CollisionStatus

type CollisionStatus string

CollisionStatus records whether known competing work exists.

const (
	CollisionUnknown   CollisionStatus = "unknown"
	CollisionNone      CollisionStatus = "none"
	CollisionPossible  CollisionStatus = "possible"
	CollisionConfirmed CollisionStatus = "confirmed"
	CollisionBlocked   CollisionStatus = "blocked"
)

type CreateHypothesisInput

type CreateHypothesisInput struct {
	Title              string
	Description        string
	Category           Category
	ExpectedBehavior   string
	ObservedBehavior   string
	PotentialImpact    string
	OpenQuestions      []string
	AffectedComponents []string
	SourceRefs         []domain.SourceRef
	Links              []Link
}

CreateHypothesisInput carries all structured fields for a new hypothesis.

type EvidenceStore

type EvidenceStore interface {
	CreateEvidence(ctx context.Context, e *evidence.Evidence) error
	ListEvidence(ctx context.Context, filter evidence.EvidenceFilter) ([]*evidence.Evidence, error)
}

EvidenceStore is the subset of evidence operations the investigation service needs.

type Hypothesis

type Hypothesis struct {
	ID                 string
	InvestigationID    string
	Title              string
	Description        string
	Category           Category
	ExpectedBehavior   string
	ObservedBehavior   string
	PotentialImpact    string
	OpenQuestions      []string
	AffectedComponents []string
	SourceRefs         []domain.SourceRef
	Links              []Link
	Status             HypothesisStatus
	AuditTrail         []StatusChange
	CreatedAt          time.Time
	UpdatedAt          time.Time
}

Hypothesis is a possible bug or improvement that has not yet met an evidence threshold.

func (*Hypothesis) Transition

func (h *Hypothesis) Transition(to HypothesisStatus, rationale string) error

Transition advances the hypothesis status if allowed and records a status change.

type HypothesisStatus

type HypothesisStatus string

HypothesisStatus is the lifecycle of an individual hypothesis.

const (
	HypothesisProposed   HypothesisStatus = "proposed"
	HypothesisPromoted   HypothesisStatus = "promoted"
	HypothesisRejected   HypothesisStatus = "rejected"
	HypothesisDeferred   HypothesisStatus = "deferred"
	HypothesisSuperseded HypothesisStatus = "superseded"
)

type Investigation

type Investigation struct {
	ID               string
	Repo             domain.RepoRef
	CommitSHA        string
	Lens             string
	Status           InvestigationStatus
	ThreadBaseline   *ThreadBaseline
	SeedHypothesisID string
	AuditTrail       []StatusChange
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

Investigation is a durable workspace scoped to a repository and commit.

type InvestigationStatus

type InvestigationStatus string

InvestigationStatus is the high-level state of the workspace.

const (
	InvestigationOpen   InvestigationStatus = "open"
	InvestigationClosed InvestigationStatus = "closed"
)
type Link struct {
	Kind   string
	Ref    string
	Source domain.SourceRef
}

Link is an explicit reference to an issue, PR, commit, file, test, or other hypothesis.

type Opportunity

type Opportunity struct {
	ID                  string
	InvestigationID     string
	HypothesisID        string
	Title               string
	ProblemStatement    string
	Category            Category
	Scope               string
	Impact              string
	Confidence          float64
	ExpectedEffort      string
	Dependencies        []string
	CollisionStatus     CollisionStatus
	MaintainerAlignment string
	SourceRefs          []domain.SourceRef
	EvidenceIDs         []string
	Status              OpportunityStatus
	AuditTrail          []StatusChange
	CreatedAt           time.Time
	UpdatedAt           time.Time
}

Opportunity is a scoped potential contribution with evidence, impact, and collision status.

func (*Opportunity) ContradictingEvidence

func (o *Opportunity) ContradictingEvidence(all []*evidence.Evidence) []*evidence.Evidence

ContradictingEvidence returns evidence items marked as contradicting.

func (*Opportunity) SupportingEvidence

func (o *Opportunity) SupportingEvidence(all []*evidence.Evidence) []*evidence.Evidence

SupportingEvidence returns evidence items marked as supporting.

func (*Opportunity) Transition

func (o *Opportunity) Transition(to OpportunityStatus, rationale string) error

Transition advances the opportunity status if allowed and records a status change.

type OpportunityStatus

type OpportunityStatus string

OpportunityStatus is the lifecycle of an opportunity.

const (
	OpportunityHypothesis        OpportunityStatus = "hypothesis"
	OpportunityReproduced        OpportunityStatus = "reproduced"
	OpportunityValidated         OpportunityStatus = "validated"
	OpportunityMaintainerAligned OpportunityStatus = "maintainer_aligned"
	OpportunityImplemented       OpportunityStatus = "implemented"
	OpportunitySubmitted         OpportunityStatus = "submitted"
	OpportunityMerged            OpportunityStatus = "merged"
	OpportunityRejected          OpportunityStatus = "rejected"
	OpportunityDeferred          OpportunityStatus = "deferred"
	OpportunitySuperseded        OpportunityStatus = "superseded"
)

type PromoteOpportunityInput

type PromoteOpportunityInput struct {
	ProblemStatement    string
	Scope               string
	Impact              string
	ExpectedEffort      string
	Confidence          float64
	Dependencies        []string
	MaintainerAlignment string
	EvidenceIDs         []string
	SourceRefs          []domain.SourceRef
}

PromoteOpportunityInput carries the full context for promoting a hypothesis.

type Repository

type Repository interface {
	SaveInvestigation(ctx context.Context, i *Investigation) error
	StartThreadInvestigation(ctx context.Context, i *Investigation, h *Hypothesis) (*Investigation, *Hypothesis, bool, error)
	GetInvestigation(ctx context.Context, id string) (*Investigation, error)
	ListInvestigations(ctx context.Context) ([]*Investigation, error)
	SaveHypothesis(ctx context.Context, h *Hypothesis) error
	UpdateHypothesis(ctx context.Context, previous, next *Hypothesis) error
	GetHypothesis(ctx context.Context, id string) (*Hypothesis, error)
	ListHypotheses(ctx context.Context, investigationID string) ([]*Hypothesis, error)
	SaveOpportunity(ctx context.Context, o *Opportunity) error
	UpdateOpportunity(ctx context.Context, previous, next *Opportunity, blockContradicting bool) error
	PromoteHypothesisWithEvidence(ctx context.Context, h *Hypothesis, o *Opportunity, e *evidence.Evidence) error
	GetOpportunity(ctx context.Context, id string) (*Opportunity, error)
	ListOpportunities(ctx context.Context, investigationID string) ([]*Opportunity, error)
	FindRelated(ctx context.Context, ref domain.RepoRef, category Category) ([]domain.SourceRef, error)
}

Repository is a narrow persistence boundary for investigations, hypotheses, and opportunities. Concrete stores live outside this package.

type Service

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

Service manages investigations, hypotheses, opportunities, and their evidence.

func NewService

func NewService(repo Repository, evidence EvidenceStore) *Service

NewService returns an InvestigationService backed by repo and evidence store.

func (*Service) CheckDuplicates

func (s *Service) CheckDuplicates(ctx context.Context, investigationID string) ([]domain.SourceRef, error)

CheckDuplicates returns source references for known related work in the same repository.

func (*Service) CreateHypothesis

func (s *Service) CreateHypothesis(ctx context.Context, investigationID string, in CreateHypothesisInput) (*Hypothesis, error)

CreateHypothesis stores a fully structured hypothesis under an investigation.

func (*Service) GetHypothesis

func (s *Service) GetHypothesis(ctx context.Context, id string) (*Hypothesis, error)

GetHypothesis returns a hypothesis by ID.

func (*Service) GetInvestigation

func (s *Service) GetInvestigation(ctx context.Context, id string) (*Investigation, error)

GetInvestigation returns an investigation by ID.

func (*Service) GetOpportunity

func (s *Service) GetOpportunity(ctx context.Context, id string) (*Opportunity, error)

GetOpportunity returns an opportunity by ID.

func (*Service) ListHypotheses

func (s *Service) ListHypotheses(ctx context.Context, investigationID string) ([]*Hypothesis, error)

ListHypotheses returns hypotheses for an investigation.

func (*Service) ListInvestigations

func (s *Service) ListInvestigations(ctx context.Context) ([]*Investigation, error)

ListInvestigations returns all investigations ordered by creation time.

func (*Service) ListOpportunities

func (s *Service) ListOpportunities(ctx context.Context, investigationID string) ([]*Opportunity, error)

ListOpportunities returns opportunities, optionally filtered to one investigation.

func (*Service) PromoteOpportunity

func (s *Service) PromoteOpportunity(ctx context.Context, hypothesisID, problem, scope, impact, effort string, confidence float64) (*Opportunity, error)

PromoteOpportunity converts a confirmed hypothesis into an opportunity.

func (*Service) PromoteOpportunityWithInput

func (s *Service) PromoteOpportunityWithInput(ctx context.Context, hypothesisID string, in PromoteOpportunityInput) (*Opportunity, error)

PromoteOpportunityWithInput converts a confirmed hypothesis into an opportunity using the full promotion context, including dependencies and maintainer alignment.

func (*Service) RecordEvidence

func (s *Service) RecordEvidence(ctx context.Context, opportunityID string, e *evidence.Evidence) (*evidence.Evidence, error)

RecordEvidence attaches an evidence item to an opportunity and stores it.

func (*Service) RecordHypothesis

func (s *Service) RecordHypothesis(ctx context.Context, investigationID, title, description string, category Category, refs []domain.SourceRef) (*Hypothesis, error)

RecordHypothesis stores a new hypothesis under an investigation.

func (*Service) SetOpportunityStatus

func (s *Service) SetOpportunityStatus(ctx context.Context, id string, to OpportunityStatus, rationale string) (*Opportunity, error)

SetOpportunityStatus transitions an opportunity, blocking advancement when contradicting evidence is present.

func (*Service) StartFromThread

func (s *Service) StartFromThread(ctx context.Context, input StartFromThreadInput) (*StartFromThreadResult, error)

StartFromThread atomically creates an investigation and proposed hypothesis from an immutable thread baseline. Repeated requests return the existing open pair without changing its baseline.

func (*Service) StartInvestigation

func (s *Service) StartInvestigation(ctx context.Context, repo domain.RepoRef, commitSHA, lens string) (*Investigation, error)

StartInvestigation creates a new investigation for a repository and commit.

func (*Service) SummarizeEvidence

func (s *Service) SummarizeEvidence(ctx context.Context, opportunityID string) ([]*evidence.Evidence, []*evidence.Evidence, error)

SummarizeEvidence separates supporting and contradicting evidence for an opportunity.

func (*Service) TransitionHypothesis

func (s *Service) TransitionHypothesis(ctx context.Context, id string, to HypothesisStatus, rationale string) (*Hypothesis, error)

TransitionHypothesis advances a hypothesis through its lifecycle.

func (*Service) UpdateCollisionStatus

func (s *Service) UpdateCollisionStatus(ctx context.Context, id string, status CollisionStatus, rationale string) (*Opportunity, error)

UpdateCollisionStatus explicitly sets the collision status with rationale.

func (*Service) UpdateHypothesis

func (s *Service) UpdateHypothesis(ctx context.Context, id string, in UpdateHypothesisInput) (*Hypothesis, error)

UpdateHypothesis deliberately overwrites the structured fields of a hypothesis. A non-empty rationale is recorded in the audit trail.

type StartFromThreadInput

type StartFromThreadInput struct {
	Baseline    ThreadBaseline
	Title       string
	Description string
}

StartFromThreadInput contains source-backed values for the atomic start operation. Description may be bounded by the application adapter, which must record that fact on Baseline.

type StartFromThreadResult

type StartFromThreadResult struct {
	Investigation *Investigation
	Hypothesis    *Hypothesis
	Created       bool
}

StartFromThreadResult reports whether a new pair was created or an existing open investigation for the same thread was returned.

type StatusChange

type StatusChange struct {
	From      string
	To        string
	Rationale string
	At        time.Time
}

StatusChange records a deliberate lifecycle transition with rationale.

type ThreadBaseline

type ThreadBaseline struct {
	Repo                 domain.RepoRef
	Kind                 domain.ThreadKind
	Number               int
	ObservationID        int64
	SourceUpdatedAt      time.Time
	ObservationSequence  int64
	ObservedAt           time.Time
	Source               domain.SourceRef
	DescriptionTruncated bool
}

ThreadBaseline identifies the immutable stored observation from which an investigation and its seed hypothesis were created.

func (ThreadBaseline) OriginKey

func (b ThreadBaseline) OriginKey() string

OriginKey returns the case-insensitive identity used to prevent duplicate open investigations for the same source thread.

func (ThreadBaseline) Ref

func (b ThreadBaseline) Ref() string

Ref returns a stable explicit thread reference.

func (ThreadBaseline) Validate

func (b ThreadBaseline) Validate() error

Validate ensures the baseline can identify both a source thread and one immutable local observation.

type UpdateHypothesisInput

type UpdateHypothesisInput struct {
	Title              string
	Description        string
	Category           Category
	ExpectedBehavior   string
	ObservedBehavior   string
	PotentialImpact    string
	OpenQuestions      []string
	AffectedComponents []string
	SourceRefs         []domain.SourceRef
	Links              []Link
	Rationale          string
}

UpdateHypothesisInput carries all structured fields for a deliberate update.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL