cli

type AcquisitionResult struct {
	Repo          RepoRef `json:"repo"`
	Remote        string  `json:"remote"`
	DefaultBranch string  `json:"default_branch"`
	CommitSHA     string  `json:"commit_sha"`
	Files         int     `json:"files"`
	Bytes         int     `json:"bytes"`
	Indexed       bool    `json:"indexed"`
	Inserted      bool    `json:"inserted"`
	AcquiredAt    string  `json:"acquired_at"`
	Message       string  `json:"message"`
}

type AcquisitionService interface {
	Acquire(ctx context.Context, repo RepoRef, remote string) (*AcquisitionResult, error)
}

type ArchiveService interface {
	ArchiveSync(ctx context.Context, repo RepoRef, opts ArchiveSyncOptions) (*SyncResult, error)
	Hydrate(ctx context.Context, repo RepoRef, number int, opts HydrateOptions) (*HydrateResult, error)
}

type ArchiveSyncOptions struct {
	State    string
	Since    time.Duration
	Numbers  []int
	MaxPages int
}

type ArchiveThreadService interface {
	ArchiveThreads(ctx context.Context, repo RepoRef, kind, state string, limit int) (*ThreadListResult, error)
}

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

type CLIError struct {
	Code int
	Err  error
}

type ClusterListResult struct {
	Repo     RepoRef         `json:"repo"`
	Total    int             `json:"total"`
	Clusters []ClusterResult `json:"clusters"`
}

type ClusterMember struct {
	Kind     string  `json:"kind"`
	Owner    string  `json:"owner"`
	Repo     string  `json:"repo"`
	Number   int     `json:"number"`
	Title    string  `json:"title,omitempty"`
	State    string  `json:"state,omitempty"`
	Score    float64 `json:"score"`
	Reason   string  `json:"reason"`
	Included bool    `json:"included"`
}

type ClusterResult struct {
	StableID    string          `json:"stable_id"`
	State       string          `json:"state"`
	Canonical   ClusterMember   `json:"canonical"`
	MemberCount int             `json:"member_count"`
	Members     []ClusterMember `json:"members,omitempty"`
}

type ClusteringService interface {
	Clusters(ctx context.Context, repo RepoRef, limit int) (*ClusterListResult, error)
	Cluster(ctx context.Context, id string, limit int) (*ClusterResult, error)
}

type CollectionListResult struct {
	Collections []CollectionResult `json:"collections"`
}

type CollectionMember struct {
	Kind string `json:"kind"`
	Ref  string `json:"ref"`
}

type CollectionResult struct {
	Name        string `json:"name"`
	MemberCount int    `json:"member_count"`
	CreatedAt   string `json:"created_at"`
	UpdatedAt   string `json:"updated_at"`
}

type CollectionService interface {
	CreateCollection(ctx context.Context, name string) (*CollectionResult, error)
	AddCollectionMembers(ctx context.Context, name string, members []CollectionMember) (*CollectionResult, error)
	ListCollections(ctx context.Context) (*CollectionListResult, error)
}

type ConfigResult struct {
	Database         string `json:"database"`
	TokenSource      string `json:"token_source"`
	TokenSourceKey   string `json:"token_source_key,omitempty"`
	CrawlBudget      int    `json:"crawl_budget"`
	CrawlConcurrency int    `json:"crawl_concurrency"`
	CrawlRetryLimit  int    `json:"crawl_retry_limit"`
	CrawlTimeout     string `json:"crawl_timeout"`
	OutputFormat     string `json:"output_format"`
	OutputMaxResults int    `json:"output_max_results"`
}

type ConfigureOptions struct {
	Database         *string
	TokenSource      *string
	TokenSourceKey   *string
	CrawlBudget      *int
	CrawlConcurrency *int
	CrawlRetryLimit  *int
	CrawlTimeout     *string
	OutputFormat     *string
	OutputMaxResults *int
	DryRun           bool
}

type ConfigureResult struct {
	Path    string       `json:"path"`
	DryRun  bool         `json:"dry_run"`
	Changed bool         `json:"changed"`
	Config  ConfigResult `json:"config"`
}

type ContributionListResult struct {
	Contributions []ContributionResult `json:"contributions"`
	Limit         int                  `json:"limit"`
	Total         int                  `json:"total"`
}

type ContributionOutcomeListResult struct {
	ContributionID string                      `json:"contribution_id"`
	Outcomes       []ContributionOutcomeResult `json:"outcomes"`
}

type ContributionOutcomeResult struct {
	ID             string `json:"id"`
	ContributionID string `json:"contribution_id"`
	Outcome        string `json:"outcome"`
	Reason         string `json:"reason,omitempty"`
	SourceEventAt  string `json:"source_event_at,omitempty"`
	CreatedAt      string `json:"created_at"`
}

type ContributionResult struct {
	ID            string         `json:"id"`
	OpportunityID string         `json:"opportunity_id"`
	Kind          string         `json:"kind"`
	Title         string         `json:"title"`
	Body          string         `json:"body,omitempty"`
	Reference     string         `json:"reference,omitempty"`
	ReferenceURL  string         `json:"reference_url,omitempty"`
	PreparedAt    string         `json:"prepared_at"`
	SubmittedAt   string         `json:"submitted_at,omitempty"`
	CreatedAt     string         `json:"created_at"`
	UpdatedAt     string         `json:"updated_at"`
	Metadata      map[string]any `json:"metadata,omitempty"`
}

type ContributionService interface {
	PrepareIssue(ctx context.Context, opportunityID string, opts PrepareIssueOptions) (*DraftResult, error)
	PreparePullRequest(ctx context.Context, opportunityID string, opts PreparePROptions) (*DraftResult, error)
}

type ControlCounts struct {
	Repositories  int `json:"repositories"`
	Threads       int `json:"threads"`
	Sources       int `json:"sources"`
	FrontierReady int `json:"frontier_ready"`
	ActiveRuns    int `json:"active_runs"`
	ActiveJobs    int `json:"active_jobs"`
}

type ControlService interface {
	Metadata(ctx context.Context) (*MetadataResult, error)
	Configure(ctx context.Context, opts ConfigureOptions) (*ConfigureResult, error)
	ControlStatus(ctx context.Context) (*ControlStatusResult, error)
	Doctor(ctx context.Context) (*DoctorResult, error)
}

type ControlStatusResult struct {
	Healthy        bool             `json:"healthy"`
	Corpus         string           `json:"corpus"`
	Version        string           `json:"version"`
	SchemaVersion  int64            `json:"schema_version"`
	Counts         ControlCounts    `json:"counts"`
	FreshestSource string           `json:"freshest_source,omitempty"`
	RateLimits     []RateLimitState `json:"rate_limits,omitempty"`
	Warnings       []string         `json:"warnings"`
}

type CoverageFacet struct {
	Facet     string `json:"facet"`
	Present   bool   `json:"present"`
	Complete  bool   `json:"complete"`
	UpdatedAt string `json:"updated_at,omitempty"`
}

type CoverageResult struct {
	Repo   RepoRef         `json:"repo"`
	Facets []CoverageFacet `json:"facets"`
}

type CrawlOptions struct {
	Since  time.Duration
	Budget int
}

type CrawlResult struct {
	Source       string `json:"source"`
	Windows      int    `json:"windows"`
	Repositories int    `json:"repositories"`
	Threads      int    `json:"threads,omitempty"`
	Events       int    `json:"events,omitempty"`
	Requests     int    `json:"requests"`
	Imported     int    `json:"imported,omitempty"`
	Skipped      int    `json:"skipped,omitempty"`
	Failures     int    `json:"failures,omitempty"`
	Checkpoint   string `json:"checkpoint"`
}

type DefineValidationOptions struct {
	Kind           string
	Command        string
	WorkingDir     string
	BaseWorkingDir string
	CandidateDir   string
	Env            []string
	Timeout        time.Duration
	MaxOutputBytes int64
}

type DiscoveryService interface {
	AddSearchSource(ctx context.Context, name, query string) (*SourceResult, error)
	AddRepoSource(ctx context.Context, name string, refs []RepoRef) (*SourceResult, error)
	AddGHArchiveSource(ctx context.Context, name string, events []string) (*SourceResult, error)
	ShowSource(ctx context.Context, name string) (*SourceResult, error)
	ListSources(ctx context.Context) (*SourceListResult, error)
	Crawl(ctx context.Context, name string, opts CrawlOptions) (*CrawlResult, error)
}

type DoctorCheck struct {
	Name     string `json:"name"`
	Status   string `json:"status"`
	Required bool   `json:"required"`
	Message  string `json:"message"`
}

type DoctorResult struct {
	Healthy bool          `json:"healthy"`
	Checks  []DoctorCheck `json:"checks"`
}

type DossierExtensionService interface {
	BuildDossierForCLI(ctx context.Context, repo RepoRef) (any, error)
	GetDossierForCLI(ctx context.Context, repo RepoRef) (any, error)
	ExtractSeedsForCLI(ctx context.Context, repo RepoRef, classes []string, limit int) (any, error)
}

type DossierResult struct {
	Repo       RepoRef  `json:"repo"`
	Summary    string   `json:"summary"`
	Language   string   `json:"language"`
	Stars      int      `json:"stars"`
	OpenIssues int      `json:"open_issues"`
	Coverage   []string `json:"coverage"`
	Freshness  string   `json:"freshness"`
}

type DraftResult struct {
	OpportunityID string `json:"opportunity_id"`
	Kind          string `json:"kind"`
	Title         string `json:"title"`
	Body          string `json:"body"`
	RenderedAt    string `json:"rendered_at"`
}

type EvidenceItem struct {
	ID               string                         `json:"id"`
	Type             string                         `json:"type"`
	Relation         string                         `json:"relation"`
	Description      string                         `json:"description"`
	ValidationRunID  string                         `json:"validation_run_id,omitempty"`
	OpportunityID    string                         `json:"opportunity_id,omitempty"`
	SourceRefs       []WorkflowSourceRefResult      `json:"source_refs,omitempty"`
	SourceProvenance []EvidenceSourceRevisionResult `json:"source_provenance,omitempty"`
	Freshness        string                         `json:"freshness"`
	FreshnessReason  string                         `json:"freshness_reason,omitempty"`
	CreatedAt        string                         `json:"created_at"`
}

type EvidenceResult struct {
	InvestigationID string         `json:"investigation_id"`
	Evidence        []EvidenceItem `json:"evidence"`
}

type EvidenceService interface {
	ShowEvidence(ctx context.Context, investigationID string) (*EvidenceResult, error)
}

type EvidenceSourceRevisionResult struct {
	Subject             EvidenceSourceSubjectResult `json:"subject"`
	SourceUpdatedAt     string                      `json:"source_updated_at,omitempty"`
	ObservationSequence int64                       `json:"observation_sequence"`
	ObservedAt          string                      `json:"observed_at"`
}

type EvidenceSourceSubjectResult struct {
	Kind       string `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"`
}

type ExportResult struct {
	Kind    string `json:"kind"`
	Format  string `json:"format"`
	Content string `json:"content"`
}

type ExportService interface {
	ExportDossier(ctx context.Context, repo RepoRef, format string) (*ExportResult, error)
	ExportEvidence(ctx context.Context, investigationID, format string) (*ExportResult, error)
}

type HealthService interface {
	RepositoryHealthWithOptions(ctx context.Context, repo RepoRef, opts health.Options) (*health.Report, error)
}

type HydrateOptions struct {
	Facets   []string
	MaxPages int
}

type HydrateResult struct {
	Repo     RepoRef         `json:"repo"`
	Number   int             `json:"number"`
	Kind     string          `json:"kind"`
	Facets   []HydratedFacet `json:"facets"`
	Pages    int             `json:"pages"`
	Requests int             `json:"requests"`
	Message  string          `json:"message"`
}

type HydratedFacet struct {
	Facet    string `json:"facet"`
	Count    int    `json:"count"`
	Pages    int    `json:"pages"`
	Complete bool   `json:"complete"`
}

type HypothesisListResult struct {
	Hypotheses []HypothesisResult `json:"hypotheses"`
}

type HypothesisResult struct {
	ID              string                    `json:"id"`
	InvestigationID string                    `json:"investigation_id"`
	Title           string                    `json:"title"`
	Description     string                    `json:"description"`
	Category        string                    `json:"category"`
	Status          string                    `json:"status"`
	SourceRefs      []WorkflowSourceRefResult `json:"source_refs,omitempty"`
	Links           []WorkflowLinkResult      `json:"links,omitempty"`
	AuditTrail      []WorkflowAuditResult     `json:"audit_trail,omitempty"`
	CreatedAt       string                    `json:"created_at"`
	UpdatedAt       string                    `json:"updated_at"`
}

type HypothesisUpdateOptions struct {
	Title              *string
	Description        *string
	Category           *string
	ExpectedBehavior   *string
	ObservedBehavior   *string
	PotentialImpact    *string
	OpenQuestions      []string
	AffectedComponents []string
	Rationale          string
}

type IndexResult struct {
	Repo     RepoRef `json:"repo"`
	Path     string  `json:"path"`
	Commit   string  `json:"commit"`
	Files    int     `json:"files"`
	Bytes    int     `json:"bytes"`
	Inserted bool    `json:"inserted"`
	Message  string  `json:"message"`
}

type InitResult struct {
	Path    string `json:"path"`
	Message string `json:"message"`
}

type InvestigationListResult struct {
	Investigations []InvestigationResult `json:"investigations"`
}

type InvestigationResult struct {
	ID               string                `json:"id"`
	Repo             RepoRef               `json:"repo"`
	CommitSHA        string                `json:"commit_sha,omitempty"`
	Lens             string                `json:"lens,omitempty"`
	Status           string                `json:"status"`
	ThreadBaseline   *ThreadBaselineResult `json:"thread_baseline,omitempty"`
	SeedHypothesisID string                `json:"seed_hypothesis_id,omitempty"`
	AuditTrail       []WorkflowAuditResult `json:"audit_trail,omitempty"`
	CreatedAt        string                `json:"created_at"`
	UpdatedAt        string                `json:"updated_at"`
}

type InvestigationService interface {
	StartInvestigation(ctx context.Context, repo RepoRef, commit, lens string) (*InvestigationResult, error)
	ShowInvestigation(ctx context.Context, id string) (*InvestigationResult, error)
	ListInvestigations(ctx context.Context) (*InvestigationListResult, error)
	AddHypothesis(ctx context.Context, investigationID, title, description, category string) (*HypothesisResult, error)
	ListHypotheses(ctx context.Context, investigationID string) (*HypothesisListResult, error)
	PromoteOpportunity(ctx context.Context, hypothesisID, problem, scope, impact, effort string, confidence float64) (*OpportunityResult, error)
	ShowOpportunity(ctx context.Context, id string) (*OpportunityResult, error)
	ListOpportunities(ctx context.Context, investigationID string) (*OpportunityListResult, error)
	SetOpportunityStatus(ctx context.Context, id, status, rationale string) (*OpportunityResult, error)
}

type JobListResult struct {
	Jobs []JobResult `json:"jobs"`
}

type JobResult struct {
	ID           string `json:"id"`
	Kind         string `json:"kind"`
	Status       string `json:"status"`
	Request      string `json:"request,omitempty"`
	Result       string `json:"result,omitempty"`
	Error        string `json:"error,omitempty"`
	Progress     string `json:"progress,omitempty"`
	Statistics   string `json:"statistics,omitempty"`
	CreatedAt    string `json:"created_at"`
	StartedAt    string `json:"started_at,omitempty"`
	CompletedAt  string `json:"completed_at,omitempty"`
	CancelledAt  string `json:"cancelled_at,omitempty"`
	Cancellation bool   `json:"cancellation_requested"`
}

type JobService interface {
	ListJobs(ctx context.Context, status string, limit int) (*JobListResult, error)
	GetJob(ctx context.Context, id string) (*JobResult, error)
	CancelJob(ctx context.Context, id string) (*JobResult, error)
}

type LensExplainCandidate struct {
	Kind      string  `json:"kind"`
	Repo      RepoRef `json:"repo"`
	Number    int     `json:"number,omitempty"`
	Title     string  `json:"title"`
	State     string  `json:"state,omitempty"`
	URL       string  `json:"url,omitempty"`
	UpdatedAt string  `json:"updated_at,omitempty"`
}

type LensExplainOptions struct {
	Query        string
	Repo         string
	Kind         string
	State        string
	Author       string
	Association  string
	Assignee     string
	Labels       []string
	UpdatedAfter time.Time
}

type LensExplainResult struct {
	Lens            LensResult           `json:"lens"`
	Candidate       LensExplainCandidate `json:"candidate"`
	Query           string               `json:"query,omitempty"`
	PopulationSize  int                  `json:"population_size"`
	PopulationScope string               `json:"population_scope"`
	EvaluatedAt     string               `json:"evaluated_at"`
	Score           float64              `json:"score"`
	Signals         []LensExplainSignal  `json:"signals"`
	MissingSignals  []string             `json:"missing_signals,omitempty"`
}

type LensExplainSignal struct {
	Name         string  `json:"name"`
	Value        float64 `json:"value,omitempty"`
	Normalized   float64 `json:"normalized,omitempty"`
	Weight       float64 `json:"weight"`
	Contribution float64 `json:"contribution"`
	Missing      bool    `json:"missing"`
}

type LensListResult struct {
	Lenses []LensResult `json:"lenses"`
}

type LensResult struct {
	Name       string          `json:"name"`
	Definition lens.Definition `json:"definition"`
	CreatedAt  string          `json:"created_at"`
	UpdatedAt  string          `json:"updated_at"`
}

type LensService interface {
	AddLens(ctx context.Context, name string, def lens.Definition) (*LensResult, error)
	ListLenses(ctx context.Context) (*LensListResult, error)
	ShowLens(ctx context.Context, name string) (*LensResult, error)
	ExplainLens(ctx context.Context, name, ref string, opts LensExplainOptions) (*LensExplainResult, error)
}

type ListContributionsOptions struct {
	OpportunityID string
	Kind          string
	Limit         int
}

type ListTriageEventsOptions struct {
	TargetKind string
	TargetRef  string
	Outcome    string
	Lens       string
	Limit      int
}

type LocalQueryService interface {
	Coverage(ctx context.Context, repo RepoRef) (*CoverageResult, error)
	RunHistory(ctx context.Context, limit int) (*RunListResult, error)
	NeighborQuery(ctx context.Context, repo RepoRef, kind string, number, limit int) (*NeighborListResult, error)
}

type MCPOptions struct {
	Transport string
}

type MCPRunner interface {
	Run(ctx context.Context, opts MCPOptions) error
}

type MetadataExportOptions struct {
	Limit int
}

type MetadataExportResult struct {
	SchemaVersion        int             `json:"schema_version"`
	Data                 json.RawMessage `json:"data"`
	TriageEvents         int             `json:"triage_events"`
	Contributions        int             `json:"contributions"`
	ContributionOutcomes int             `json:"contribution_outcomes"`
	Evidence             int             `json:"evidence"`
}

type MetadataImportOptions struct {
	Data []byte
}

type MetadataImportResult struct {
	SchemaVersion        int `json:"schema_version"`
	TriageEvents         int `json:"triage_events"`
	Contributions        int `json:"contributions"`
	ContributionOutcomes int `json:"contribution_outcomes"`
	Evidence             int `json:"evidence"`
}

type MetadataResult struct {
	Name          string          `json:"name"`
	Version       string          `json:"version"`
	GoVersion     string          `json:"go_version"`
	OS            string          `json:"os"`
	Architecture  string          `json:"architecture"`
	SchemaVersion int64           `json:"schema_version"`
	ConfigPath    string          `json:"config_path"`
	CorpusPath    string          `json:"corpus_path"`
	Capabilities  []string        `json:"capabilities"`
	Features      map[string]bool `json:"features"`
}

type NeighborListResult struct {
	Repo           RepoRef          `json:"repo"`
	Kind           string           `json:"kind"`
	Number         int              `json:"number"`
	SourceRevision string           `json:"source_revision"`
	Neighbors      []NeighborResult `json:"neighbors"`
}

type NeighborResult struct {
	Kind   string  `json:"kind"`
	Repo   RepoRef `json:"repo"`
	Number int     `json:"number"`
	Title  string  `json:"title"`
	State  string  `json:"state"`
	Score  float64 `json:"score"`
	Reason string  `json:"reason"`
}

type OpportunityListResult struct {
	Opportunities []OpportunityResult `json:"opportunities"`
	Filter        string              `json:"filter,omitempty"`
}

type OpportunityResult struct {
	ID               string  `json:"id"`
	InvestigationID  string  `json:"investigation_id"`
	HypothesisID     string  `json:"hypothesis_id"`
	Title            string  `json:"title"`
	ProblemStatement string  `json:"problem_statement"`
	Category         string  `json:"category"`
	Scope            string  `json:"scope"`
	Impact           string  `json:"impact"`
	ExpectedEffort   string  `json:"expected_effort"`
	Confidence       float64 `json:"confidence"`
	CollisionStatus  string  `json:"collision_status"`
	Status           string  `json:"status"`
	CreatedAt        string  `json:"created_at"`
	UpdatedAt        string  `json:"updated_at"`
}

type PrepareIssueOptions struct {
	Guidance string
	Success  string
}

type PreparePROptions struct {
	WorkspaceID   string
	Approach      string
	Changes       string
	Compatibility string
	Limitations   string
	LinkedIssue   string
	Guidance      string
}

type RadarOptions struct {
	Repo  RepoRef
	Limit int
}

type RadarService interface {
	ContributionRadar(ctx context.Context, opts RadarOptions) (*radar.Report, error)
}

type RateLimitState struct {
	Resource   string `json:"resource"`
	Limit      int    `json:"limit"`
	Remaining  int    `json:"remaining"`
	Used       int    `json:"used"`
	ResetAt    string `json:"reset_at,omitempty"`
	StatusCode int    `json:"status_code"`
	ObservedAt string `json:"observed_at"`
}

type ReadinessCheck struct {
	CheckID      string   `json:"check_id"`
	RuleID       string   `json:"rule_id"`
	RuleVersion  string   `json:"rule_version"`
	Status       string   `json:"status"`
	Summary      string   `json:"summary"`
	EvidenceRefs []string `json:"evidence_refs,omitempty"`
	Remediation  string   `json:"remediation,omitempty"`
	EvaluatedAt  string   `json:"evaluated_at"`
}

type ReadinessResult struct {
	OpportunityID  string           `json:"opportunity_id"`
	RuleSetVersion string           `json:"rule_set_version"`
	Status         string           `json:"status"`
	EvaluatedAt    string           `json:"evaluated_at"`
	Checks         []ReadinessCheck `json:"checks"`
}

type ReadinessService interface {
	OpportunityReadiness(ctx context.Context, opportunityID string) (*ReadinessResult, error)
	ExplainReadiness(ctx context.Context, checkID string) (*ReadinessCheck, error)
}

type RecordContributionOptions struct {
	OpportunityID string
	Kind          string
	Title         string
	Body          string
	Reference     string
	ReferenceURL  string
}

type RecordContributionOutcomeOptions struct {
	ContributionID string
	Outcome        string
	Reason         string
}

type RecordEvidenceOptions struct {
	InvestigationID string
	HypothesisID    string
	OpportunityID   string
	Type            string
	Relation        string
	Description     string
}

type RecordTriageEventOptions struct {
	Target  string
	Outcome string
	Reason  string
	Lens    string
}

type RepoRef struct {
	Owner string `json:"owner"`
	Repo  string `json:"repo"`
}

type ResearchService interface {
	ThreadResearchBrief(ctx context.Context, ref research.ThreadRef) (*research.Brief, error)
}

type RunListResult struct {
	Runs []RunResult `json:"runs"`
}

type RunResult struct {
	ID          int64  `json:"id"`
	Kind        string `json:"kind"`
	Status      string `json:"status"`
	StartedAt   string `json:"started_at"`
	CompletedAt string `json:"completed_at,omitempty"`
	Stats       string `json:"stats,omitempty"`
	Error       string `json:"error,omitempty"`
}

type RunValidationOptions struct {
	Kind    string
	Execute bool
}

type SearchMatch struct {
	Kind      string   `json:"kind"`
	Repo      RepoRef  `json:"repo"`
	Title     string   `json:"title"`
	Number    int      `json:"number,omitempty"`
	State     string   `json:"state,omitempty"`
	Author    string   `json:"author,omitempty"`
	Labels    []string `json:"labels,omitempty"`
	URL       string   `json:"url,omitempty"`
	Score     float64  `json:"score"`
	Body      string   `json:"-"`
	Freshness string   `json:"freshness,omitempty"`
	Coverage  []string `json:"coverage,omitempty"`
}

type SearchOptions struct {
	Kind         string
	Repo         string
	State        string
	Author       string
	Association  string
	Assignee     string
	Labels       []string
	UpdatedAfter time.Time
	Limit        int
	Cursor       string
	Lens         string
}

type SearchResult struct {
	Query      string        `json:"query"`
	Kind       string        `json:"kind"`
	Repo       string        `json:"repo,omitempty"`
	Limit      int           `json:"limit"`
	Total      int           `json:"total"`
	Matches    []SearchMatch `json:"matches"`
	NextCursor string        `json:"next_cursor,omitempty"`
}

type Service interface {
	Init(ctx context.Context) (*InitResult, error)
	Status(ctx context.Context) (*StatusResult, error)
	Sync(ctx context.Context, repo RepoRef) (*SyncResult, error)
	Search(ctx context.Context, query string, opts SearchOptions) (*SearchResult, error)
	Dossier(ctx context.Context, repo RepoRef) (*DossierResult, error)
	Index(ctx context.Context, repo RepoRef, path string) (*IndexResult, error)
}

type SetupOptions struct {
	Remove     bool
	Clients    []string
	AllClients bool

	// InstallCLI explicitly authorizes a global npm installation of the running
	// GitContribute version. It is never inferred in non-interactive operation.
	InstallCLI bool
	// SkipMCP selects terminal-only setup. An empty Clients slice without
	// SkipMCP means detect installed clients rather than disable MCP.
	SkipMCP bool

	TokenSource    string
	TokenSourceKey string
	Repository     string
	DryRun         bool
	// Version is the release used for both persistent installation and an npx
	// MCP launcher. Empty values inherit the running service version.
	Version string
	// Executable and Environment are runtime evidence used to choose a stable
	// MCP launcher. They are injectable so setup behavior is testable without
	// capturing a temporary npm-cache executable.
	Executable  string
	Environment map[string]string
}

type SetupReport struct {
	Operation string      `json:"operation"`
	DryRun    bool        `json:"dry_run"`
	Launcher  string      `json:"launcher,omitempty"`
	Steps     []SetupStep `json:"steps"`
}

type SetupService interface {
	Setup(ctx context.Context, opts SetupOptions) (*SetupReport, error)
}

type SetupStep struct {
	Name    string `json:"name"`
	Path    string `json:"path,omitempty"`
	Status  string `json:"status"`
	Message string `json:"message,omitempty"`
}

type SourceListResult struct {
	Sources []SourceResult `json:"sources"`
}

type SourceResult struct {
	Name       string `json:"name"`
	Kind       string `json:"kind"`
	Definition string `json:"definition"`
	Enabled    bool   `json:"enabled"`
}

type StatusResult struct {
	Healthy bool   `json:"healthy"`
	Corpus  string `json:"corpus"`
	Version string `json:"version"`
	Message string `json:"message"`
}

type SyncResult struct {
	Repo    RepoRef `json:"repo"`
	Updated int     `json:"updated"`
	Message string  `json:"message"`
}

type TUIOptions struct {
	Repo RepoRef
	JSON bool
}

type TUIRunner interface {
	Run(ctx context.Context, opts TUIOptions) error
}

type TailOptions struct {
	Since    time.Duration
	Budget   int
	Interval time.Duration
	Once     bool
}

type TailResult struct {
	Source     string       `json:"source"`
	Iterations int          `json:"iterations"`
	Last       *CrawlResult `json:"last,omitempty"`
}

type TailService interface {
	TailSource(ctx context.Context, name string, opts TailOptions) (*TailResult, error)
}

type ThreadBaselineResult struct {
	Ref                  string                  `json:"ref"`
	Repository           string                  `json:"repository"`
	Kind                 string                  `json:"kind"`
	Number               int                     `json:"number"`
	ObservationID        int64                   `json:"observation_id"`
	SourceUpdatedAt      string                  `json:"source_updated_at,omitempty"`
	ObservationSequence  int64                   `json:"observation_sequence"`
	ObservedAt           string                  `json:"observed_at,omitempty"`
	Source               WorkflowSourceRefResult `json:"source"`
	DescriptionTruncated bool                    `json:"description_truncated"`
}

type ThreadInvestigationResult struct {
	Created       bool                 `json:"created"`
	Investigation *InvestigationResult `json:"investigation"`
	Hypothesis    *HypothesisResult    `json:"hypothesis"`
}

type ThreadInvestigationService interface {
	StartInvestigationFromThread(ctx context.Context, ref research.ThreadRef) (*ThreadInvestigationResult, error)
}

type ThreadListItem struct {
	Kind      string   `json:"kind"`
	Number    int      `json:"number"`
	State     string   `json:"state"`
	Title     string   `json:"title"`
	Author    string   `json:"author,omitempty"`
	Labels    []string `json:"labels,omitempty"`
	UpdatedAt string   `json:"updated_at"`
}

type ThreadListResult struct {
	Repo      RepoRef          `json:"repo"`
	Threads   []ThreadListItem `json:"threads"`
	Freshness string           `json:"freshness,omitempty"`
	Coverage  []CoverageFacet  `json:"coverage,omitempty"`
}

type TrackingService interface {
	RecordTriageEvent(ctx context.Context, opts RecordTriageEventOptions) (*TriageEventResult, error)
	ListTriageEvents(ctx context.Context, opts ListTriageEventsOptions) (*TriageEventListResult, error)
	RecordContribution(ctx context.Context, opts RecordContributionOptions) (*ContributionResult, error)
	GetContribution(ctx context.Context, id string) (*ContributionResult, error)
	ListContributions(ctx context.Context, opts ListContributionsOptions) (*ContributionListResult, error)
	RecordContributionOutcome(ctx context.Context, opts RecordContributionOutcomeOptions) (*ContributionOutcomeResult, error)
	ListContributionOutcomes(ctx context.Context, contributionID string) (*ContributionOutcomeListResult, error)
	ExportLocalMetadata(ctx context.Context, opts MetadataExportOptions) (*MetadataExportResult, error)
	ImportLocalMetadata(ctx context.Context, opts MetadataImportOptions) (*MetadataImportResult, error)
}

type TriageEventListResult struct {
	Events []TriageEventResult `json:"events"`
	Limit  int                 `json:"limit"`
	Total  int                 `json:"total"`
}

type TriageEventResult struct {
	ID            string `json:"id"`
	TargetKind    string `json:"target_kind"`
	TargetRef     string `json:"target_ref"`
	Outcome       string `json:"outcome"`
	Reason        string `json:"reason,omitempty"`
	Lens          string `json:"lens,omitempty"`
	SourceEventAt string `json:"source_event_at,omitempty"`
	CreatedAt     string `json:"created_at"`
	UpdatedAt     string `json:"updated_at"`
}

type UpgradeOptions struct {
	Check bool
	Yes   bool
}

type UpgradeReport struct {
	Context string `json:"context"`
	Current string `json:"current"`
	Latest  string `json:"latest,omitempty"`
	Status  string `json:"status"`
	Command string `json:"command,omitempty"`
}

type UpgradeService interface {
	Upgrade(ctx context.Context, opts UpgradeOptions) (*UpgradeReport, error)
}

type ValidationComparisonResult struct {
	Base           *ValidationRunResult `json:"base"`
	Candidate      *ValidationRunResult `json:"candidate"`
	Classification string               `json:"classification"`
	Explanation    string               `json:"explanation"`
}

type ValidationResult struct {
	ID              string   `json:"id"`
	InvestigationID string   `json:"investigation_id"`
	Kind            string   `json:"kind"`
	Command         []string `json:"command"`
	WorkingDir      string   `json:"working_dir"`
	BaseWorkingDir  string   `json:"base_working_dir,omitempty"`
	CandidateDir    string   `json:"candidate_dir,omitempty"`
	Env             []string `json:"environment_allowlist,omitempty"`
	Timeout         string   `json:"timeout,omitempty"`
	MaxOutputBytes  int64    `json:"max_output_bytes,omitempty"`
	CreatedAt       string   `json:"created_at"`
}

type ValidationRunResult struct {
	ID              string `json:"id"`
	DefinitionID    string `json:"definition_id"`
	InvestigationID string `json:"investigation_id"`
	Kind            string `json:"kind"`
	ExitCode        int    `json:"exit_code"`
	Stdout          string `json:"stdout"`
	Stderr          string `json:"stderr"`
	Truncated       bool   `json:"truncated"`
	Error           string `json:"error,omitempty"`
	Classification  string `json:"classification"`
	StartedAt       string `json:"started_at"`
	CompletedAt     string `json:"completed_at"`
}

type ValidationService interface {
	DefineValidation(ctx context.Context, investigationID string, opts DefineValidationOptions) (*ValidationResult, error)
	ShowValidation(ctx context.Context, id string) (*ValidationResult, error)
	RunValidation(ctx context.Context, id string, opts RunValidationOptions) (*ValidationRunResult, error)
	CompareValidation(ctx context.Context, baseRunID, candidateRunID string) (*ValidationComparisonResult, error)
}

type WorkflowAuditResult struct {
	From      string `json:"from,omitempty"`
	To        string `json:"to"`
	Rationale string `json:"rationale"`
	At        string `json:"at"`
}

type WorkflowExtensionService interface {
	UpdateHypothesisForCLI(ctx context.Context, id string, opts HypothesisUpdateOptions) (any, error)
	TransitionHypothesisForCLI(ctx context.Context, id, status, rationale string) (any, error)
	CheckDuplicatesForCLI(ctx context.Context, target, id string, limit int) (any, error)
	CheckCollisionsForCLI(ctx context.Context, target, id string, limit int) (any, error)
	SetCollisionForCLI(ctx context.Context, id, status, rationale string) (any, error)
	RecordEvidenceForCLI(ctx context.Context, opts RecordEvidenceOptions) (any, error)
	WorkspaceDiffForCLI(ctx context.Context, id string) (any, error)
	PrepareReviewForCLI(ctx context.Context, opportunityID, workspaceID string) (any, error)
}

type WorkflowLinkResult struct {
	Kind   string                  `json:"kind"`
	Ref    string                  `json:"ref"`
	Source WorkflowSourceRefResult `json:"source"`
}

type WorkflowSourceRefResult struct {
	Source     string `json:"source"`
	URL        string `json:"url,omitempty"`
	CommitSHA  string `json:"commit_sha,omitempty"`
	ObservedAt string `json:"observed_at,omitempty"`
	AsOf       string `json:"as_of,omitempty"`
}

type WorkspaceCreateOptions struct {
	Remote       string
	BaseRef      string
	CandidateRef string
	Name         string
}

type WorkspaceResult struct {
	ID              string  `json:"id"`
	InvestigationID string  `json:"investigation_id"`
	Repo            RepoRef `json:"repo"`
	Path            string  `json:"path"`
	Remote          string  `json:"remote"`
	BaseSHA         string  `json:"base_sha"`
	CandidateSHA    string  `json:"candidate_sha"`
	MergeBase       string  `json:"merge_base"`
	Dirty           bool    `json:"dirty"`
	CreatedAt       string  `json:"created_at"`
}

type WorkspaceService interface {
	CreateWorkspace(ctx context.Context, investigationID string, opts WorkspaceCreateOptions) (*WorkspaceResult, error)
	ShowWorkspace(ctx context.Context, id string) (*WorkspaceResult, error)
}