contracts

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"`
	IndexManifest  codeindex.Manifest `json:"index_manifest"`
	ArtifactDigest string             `json:"artifact_digest"`
	ManifestDigest string             `json:"manifest_digest"`
	SnapshotToken  string             `json:"snapshot_token"`
}

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

type ArchiveService interface {
	SyncPlanningService
	RepositoryContextSync(ctx context.Context, repo RepoRef, maxRequests int) (*RepositoryContextResult, error)
	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
	MaxRequests int
}

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

type ClusterListResult struct {
	Repo       RepoRef                    `json:"repo"`
	Projection *ClusterProjectionIdentity `json:"projection,omitempty"`
	Total      int                        `json:"total"`
	Truncated  bool                       `json:"truncated"`
	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 ClusterProjectionIdentity struct {
	SourceRevision     string `json:"source_revision"`
	GovernanceRevision uint64 `json:"governance_revision"`
	RuleVersion        string `json:"rule_version"`
	RunID              int64  `json:"run_id"`
}

type ClusterRefreshResult struct {
	Repo        RepoRef                   `json:"repo"`
	Disposition string                    `json:"disposition"`
	Projection  ClusterProjectionIdentity `json:"projection"`
	Stats       ClusterRefreshStats       `json:"stats"`
}

type ClusterRefreshStats struct {
	CandidateCount  int    `json:"candidate_count"`
	PossiblePairs   uint64 `json:"possible_pairs"`
	ScoredPairs     uint64 `json:"scored_pairs"`
	ClusterCount    int    `json:"cluster_count"`
	SnapshotQueries int    `json:"snapshot_queries"`
	CommitQueries   int    `json:"commit_queries"`
}

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 {
	ListClusters(ctx context.Context, repo RepoRef, limit int) (*ClusterListResult, error)
	RefreshClusters(ctx context.Context, repo RepoRef) (*ClusterRefreshResult, error)
	Cluster(ctx context.Context, id string, limit int) (*ClusterResult, error)
}

type CollectionListResult struct {
	Collections []CollectionResult `json:"collections"`
	Total       int                `json:"total"`
	Truncated   bool               `json:"truncated"`
}

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 CollisionCheckResult struct {
	HypothesisID   string              `json:"hypothesis_id,omitempty"`
	OpportunityID  string              `json:"opportunity_id,omitempty"`
	Repo           domain.RepoRef      `json:"repo"`
	Query          string              `json:"query"`
	Findings       []evidence.Evidence `json:"findings"`
	SourceRevision string              `json:"source_revision"`
	Limit          int                 `json:"limit"`
	Total          int                 `json:"total"`
}

type ConcernCreateOptions struct {
	Repo             RepoRef
	CommitSHA        string
	WorkspaceID      string
	Title            string
	ProblemStatement string
	SuspectedOwner   string
	Confidence       float64
	Unknowns         []string
	SuccessCriterion string
	Notes            string
	EvidenceIDs      []string
}

type ConcernLinkOptions struct {
	Kind       string
	TargetType string
	TargetID   string
	Note       string
}

type ConcernLinkResult struct {
	Kind       string `json:"kind"`
	TargetType string `json:"target_type"`
	TargetID   string `json:"target_id"`
	Note       string `json:"note,omitempty"`
}

type ConcernListOptions struct {
	Repo   RepoRef
	Status string
	Query  string
	Limit  int
	Offset int
}

type ConcernListResult struct {
	Concerns  []ConcernResult `json:"concerns"`
	Limit     int             `json:"limit"`
	Total     int             `json:"total"`
	Truncated bool            `json:"truncated"`
}

type ConcernPromoteOptions struct {
	Kind           string
	Category       string
	Scope          string
	Impact         string
	ExpectedEffort string
}

type ConcernPromotionResult struct {
	Kind            string `json:"kind"`
	InvestigationID string `json:"investigation_id"`
	HypothesisID    string `json:"hypothesis_id"`
	OpportunityID   string `json:"opportunity_id,omitempty"`
}

type ConcernResult struct {
	ID               string                  `json:"id"`
	Repo             RepoRef                 `json:"repo"`
	CommitSHA        string                  `json:"commit_sha,omitempty"`
	WorkspaceID      string                  `json:"workspace_id,omitempty"`
	Title            string                  `json:"title"`
	ProblemStatement string                  `json:"problem_statement"`
	SuspectedOwner   string                  `json:"suspected_owner,omitempty"`
	Confidence       float64                 `json:"confidence"`
	Unknowns         []string                `json:"unknowns,omitempty"`
	SuccessCriterion string                  `json:"success_criterion,omitempty"`
	Notes            string                  `json:"notes,omitempty"`
	EvidenceIDs      []string                `json:"evidence_ids,omitempty"`
	SourceRefCount   int                     `json:"source_ref_count"`
	Freshness        string                  `json:"freshness"`
	FreshnessReason  string                  `json:"freshness_reason"`
	Links            []ConcernLinkResult     `json:"links,omitempty"`
	Status           string                  `json:"status"`
	Promotion        *ConcernPromotionResult `json:"promotion,omitempty"`
	CreatedAt        string                  `json:"created_at"`
	UpdatedAt        string                  `json:"updated_at"`
}

type ConcernService interface {
	CreateConcern(context.Context, ConcernCreateOptions) (*ConcernResult, error)
	ListConcerns(context.Context, ConcernListOptions) (*ConcernListResult, error)
	ShowConcern(context.Context, string) (*ConcernResult, error)
	UpdateConcern(context.Context, string, ConcernUpdateOptions) (*ConcernResult, error)
	SetConcernStatus(context.Context, string, string, string) (*ConcernResult, error)
	LinkConcern(context.Context, string, ConcernLinkOptions) (*ConcernResult, error)
	PromoteConcern(context.Context, string, ConcernPromoteOptions) (*ConcernResult, error)
}

type ConcernUpdateOptions struct {
	Title            *string
	ProblemStatement *string
	SuspectedOwner   *string
	Confidence       *float64
	Unknowns         []string
	SuccessCriterion *string
	Notes            *string
	EvidenceIDs      []string
}

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"`
}

type ConfigureOptions struct {
	Database         *string
	TokenSource      *string
	TokenSourceKey   *string
	CrawlBudget      *int
	CrawlConcurrency *int
	CrawlRetryLimit  *int
	CrawlTimeout     *string
	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 CorpusBackupResult struct {
	Path           string `json:"path"`
	ManifestPath   string `json:"manifest_path,omitempty"`
	SizeBytes      int64  `json:"size_bytes"`
	SHA256         string `json:"sha256"`
	CreatedAt      string `json:"created_at,omitempty"`
	SourceSchema   int64  `json:"source_schema,omitempty"`
	ExpectedSchema int64  `json:"expected_schema,omitempty"`
	Compatibility  string `json:"compatibility,omitempty"`
}

type CorpusInspectionResult struct {
	Path                      string                `json:"path"`
	Exists                    bool                  `json:"exists"`
	SizeBytes                 int64                 `json:"size_bytes"`
	WALBytes                  int64                 `json:"wal_bytes"`
	State                     string                `json:"state"`
	Current                   int64                 `json:"current_schema"`
	Target                    int64                 `json:"target_schema"`
	Repositories              int                   `json:"repositories"`
	Threads                   int                   `json:"threads"`
	Pending                   []CorpusMigrationStep `json:"pending_migrations"`
	Problem                   string                `json:"problem,omitempty"`
	BackupRequired            bool                  `json:"backup_required"`
	RequiredDiskBytes         uint64                `json:"required_disk_bytes"`
	AvailableDiskBytes        uint64                `json:"available_disk_bytes"`
	ProjectionRebuildRequired bool                  `json:"projection_rebuild_required"`
}

type CorpusInventoryListResult struct {
	Schema                  *CorpusInspectionResult           `json:"schema"`
	Repositories            []CorpusRepositoryInventoryResult `json:"repositories"`
	Projections             []CorpusProjectionResult          `json:"projections"`
	PendingWork             []CorpusPendingWorkResult         `json:"pending_work"`
	ObservationPayloadBytes int64                             `json:"observation_payload_bytes"`
	CodeBytes               int64                             `json:"code_bytes"`
	DatabaseBytes           int64                             `json:"database_bytes"`
	WALBytes                int64                             `json:"wal_bytes"`
	SizeAttribution         string                            `json:"size_attribution"`
}

type CorpusInventoryResult struct {
	Repo                   string `json:"repo"`
	Issues                 int    `json:"issues"`
	PullRequests           int    `json:"pull_requests"`
	Threads                int    `json:"threads"`
	RepositoryObservations int    `json:"repository_observations"`
	ThreadObservations     int    `json:"thread_observations"`
	FacetObservations      int    `json:"facet_observations"`
	FacetCoverage          int    `json:"facet_coverage"`
	CodeSnapshots          int    `json:"code_snapshots"`
	CodeDocuments          int    `json:"code_documents"`
	CodeBytes              int64  `json:"code_bytes"`
	DatabaseBytes          int64  `json:"database_bytes"`
	WALBytes               int64  `json:"wal_bytes"`
}

type CorpusLifecycleService interface {
	InspectCorpus(ctx context.Context) (*CorpusInspectionResult, error)
	MigrateCorpus(ctx context.Context, opts CorpusMigrateOptions) (*CorpusMigrationResult, error)
	BackupCorpus(ctx context.Context, destination string) (*CorpusBackupResult, error)
	RestoreCorpus(ctx context.Context, source, safetyBackup string) (*CorpusRestoreResult, error)
	InventoryCorpus(ctx context.Context, repo string) (*CorpusInventoryResult, error)
	ListCorpusInventory(ctx context.Context) (*CorpusInventoryListResult, error)
	PlanCodePrune(ctx context.Context, repo string, keepLatest int) (*CorpusPruneResult, error)
	ApplyCodePrune(ctx context.Context, repo string, keepLatest int, expectedDelete []string) (*CorpusPruneResult, error)
	PlanRepositoryRemoval(ctx context.Context, repo string) (*CorpusRepositoryRemovalResult, error)
	ApplyRepositoryRemoval(ctx context.Context, repo, expectedRevision string) (*CorpusRepositoryRemovalResult, error)
	ListCorpusProjections(ctx context.Context) (*CorpusProjectionListResult, error)
	RebuildCorpusProjection(ctx context.Context, name string) (*CorpusProjectionResult, error)
}

type CorpusMigrateOptions struct {
	BackupPath string
	NoBackup   bool
}

type CorpusMigrationResult struct {
	Before *CorpusInspectionResult `json:"before"`
	After  *CorpusInspectionResult `json:"after"`
	Backup *CorpusBackupResult     `json:"backup,omitempty"`
	Steps  []CorpusMigrationStep   `json:"steps"`
}

type CorpusMigrationStep struct {
	Version           int64  `json:"version"`
	Name              string `json:"name"`
	Phase             string `json:"phase"`
	AffectedRows      int64  `json:"affected_rows_estimate,omitempty"`
	EstimateAvailable bool   `json:"affected_rows_estimate_available,omitempty"`
	Transactional     bool   `json:"transactional,omitempty"`
	Resumable         bool   `json:"resumable,omitempty"`
	ResumeStrategy    string `json:"resume_strategy,omitempty"`
	ProjectionRebuild bool   `json:"projection_rebuild,omitempty"`
}

type CorpusPendingWorkResult struct {
	Kind   string `json:"kind"`
	Name   string `json:"name"`
	Status string `json:"status"`
	Detail string `json:"detail,omitempty"`
}

type CorpusProjectionListResult struct {
	Projections []CorpusProjectionResult `json:"projections"`
}

type CorpusProjectionResult struct {
	Name              string `json:"name"`
	Version           string `json:"version"`
	Status            string `json:"status"`
	RowCount          int64  `json:"row_count"`
	RefreshedAt       string `json:"refreshed_at,omitempty"`
	SourceRevision    string `json:"source_revision,omitempty"`
	ContentHash       string `json:"content_hash,omitempty"`
	AttemptStatus     string `json:"attempt_status,omitempty"`
	AttemptStartedAt  string `json:"attempt_started_at,omitempty"`
	AttemptFinishedAt string `json:"attempt_finished_at,omitempty"`
	AttemptError      string `json:"attempt_error,omitempty"`
}

type CorpusPruneResult struct {
	Repo         string                `json:"repo"`
	DryRun       bool                  `json:"dry_run"`
	KeepLatest   int                   `json:"keep_latest"`
	Total        int                   `json:"total_snapshots"`
	Delete       []CorpusPruneSnapshot `json:"delete"`
	Deleted      int                   `json:"deleted"`
	ReclaimBytes int64                 `json:"reclaim_bytes"`
}

type CorpusPruneSnapshot struct {
	CommitSHA string `json:"commit_sha"`
	Bytes     int64  `json:"bytes"`
}

type CorpusRepositoryInventoryResult struct {
	Repo                   string `json:"repo"`
	Issues                 int    `json:"issues"`
	PullRequests           int    `json:"pull_requests"`
	Threads                int    `json:"threads"`
	RepositoryObservations int    `json:"repository_observations"`
	ThreadObservations     int    `json:"thread_observations"`
	FacetObservations      int    `json:"facet_observations"`
	FacetCoverage          int    `json:"facet_coverage"`
	LatestObservationAt    string `json:"latest_observation_at,omitempty"`
	CodeSnapshots          int    `json:"code_snapshots"`
	CodeDocuments          int    `json:"code_documents"`
	CodeBytes              int64  `json:"code_bytes"`
}

type CorpusRepositoryRemovalResult struct {
	Repo                         string `json:"repo"`
	DryRun                       bool   `json:"dry_run"`
	Revision                     string `json:"revision"`
	RepositoryObservations       int    `json:"repository_observations"`
	Threads                      int    `json:"threads"`
	ThreadObservations           int    `json:"thread_observations"`
	FacetObservations            int    `json:"facet_observations"`
	FacetCoverage                int    `json:"facet_coverage"`
	CodeSnapshots                int    `json:"code_snapshots"`
	CodeDocuments                int    `json:"code_documents"`
	Dossiers                     int    `json:"dossiers"`
	ClusterRuns                  int    `json:"cluster_runs"`
	Clusters                     int    `json:"clusters"`
	FrontierItems                int    `json:"frontier_items"`
	DetachedTriageEvents         int    `json:"detached_triage_events"`
	RemovedPortfolioLinks        int    `json:"removed_portfolio_links"`
	RemovedResolutionRecords     int    `json:"removed_resolution_records"`
	RemovedSignalSnapshots       int    `json:"removed_signal_snapshots"`
	DetachedClusterMembers       int    `json:"detached_cluster_members"`
	PreservedInvestigations      int    `json:"preserved_investigations"`
	PreservedCrossRepoReferences int    `json:"preserved_cross_repo_references"`
}

type CorpusRestoreResult struct {
	Source       string                  `json:"source"`
	Before       *CorpusInspectionResult `json:"before,omitempty"`
	After        *CorpusInspectionResult `json:"after"`
	SafetyBackup *CorpusBackupResult     `json:"safety_backup,omitempty"`
	Restored     *CorpusBackupResult     `json:"restored"`
}

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
	WorkspaceID          string
	BaseWorkspaceID      string
	CandidateWorkspaceID string
	Env                  []string
	Timeout              time.Duration
	MaxOutputBytes       int64
	Observation          *ValidationObservationContract
	Protocol             string
	ReadinessTimeout     time.Duration
}

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 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 DossierService interface {
	BuildRepositoryDossier(ctx context.Context, repo RepoRef) (*domain.Dossier, error)
	GetRepositoryDossier(ctx context.Context, repo RepoRef) (*domain.Dossier, error)
	ExtractSeeds(ctx context.Context, repo RepoRef, opts domain.ExtractSeedsOptions) ([]domain.Seed, error)
}

type DraftDiagnosticResult struct {
	Code       string `json:"code"`
	Severity   string `json:"severity"`
	Message    string `json:"message"`
	ByteOffset int    `json:"byte_offset,omitempty"`
}

type DraftResult struct {
	ID            string                  `json:"id"`
	Revision      int                     `json:"revision"`
	OpportunityID string                  `json:"opportunity_id"`
	Kind          string                  `json:"kind"`
	Repository    string                  `json:"repository"`
	Title         string                  `json:"title"`
	Body          string                  `json:"body"`
	TitleBytes    int                     `json:"title_bytes"`
	BodyBytes     int                     `json:"body_bytes"`
	TitleSHA256   string                  `json:"title_sha256"`
	BodySHA256    string                  `json:"body_sha256"`
	EvidenceIDs   []string                `json:"evidence_ids,omitempty"`
	Warnings      []DraftDiagnosticResult `json:"warnings,omitempty"`
	RenderedAt    string                  `json:"rendered_at"`
	ManifestID    string                  `json:"manifest_id,omitempty"`
}

type DuplicateCheckResult struct {
	HypothesisID   string              `json:"hypothesis_id,omitempty"`
	OpportunityID  string              `json:"opportunity_id,omitempty"`
	Repo           domain.RepoRef      `json:"repo"`
	Query          string              `json:"query"`
	Findings       []evidence.Evidence `json:"findings"`
	SourceRevision string              `json:"source_revision"`
	Limit          int                 `json:"limit"`
	Total          int                 `json:"total"`
}

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 EvidenceSummary struct {
	Supporting    int `json:"supporting"`
	Contradicting int `json:"contradicting"`
	Inconclusive  int `json:"inconclusive"`
	Stale         int `json:"stale"`
	Invalid       int `json:"invalid"`
	Total         int `json:"total"`
}

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)
	ExportManifest(ctx context.Context, opportunityID string, opts ManifestExportOptions) (*ExportResult, error)
}

type ExternalEvidenceClaim struct {
	ID           string         `json:"id"`
	Type         string         `json:"type"`
	Relation     string         `json:"relation"`
	Description  string         `json:"description"`
	SourceRefs   []string       `json:"source_refs,omitempty"`
	Measurements map[string]any `json:"measurements,omitempty"`
}

type ExternalEvidenceManifest struct {
	SchemaVersion   string                  `json:"schema_version"`
	Producer        string                  `json:"producer"`
	InvestigationID string                  `json:"investigation_id"`
	HypothesisID    string                  `json:"hypothesis_id,omitempty"`
	OpportunityID   string                  `json:"opportunity_id,omitempty"`
	Repository      string                  `json:"repository"`
	Revision        string                  `json:"revision"`
	ArtifactSHA256  string                  `json:"artifact_sha256,omitempty"`
	ObservedAt      time.Time               `json:"observed_at"`
	Environment     map[string]string       `json:"environment,omitempty"`
	Completeness    string                  `json:"completeness"`
	Integrity       string                  `json:"integrity"`
	Limitations     []string                `json:"limitations,omitempty"`
	Claims          []ExternalEvidenceClaim `json:"claims"`
	ManifestSHA256  string                  `json:"manifest_sha256"`
}

type ExternalValidationProvenance struct {
	SchemaVersion  string            `json:"schema_version"`
	Producer       string            `json:"producer"`
	ValidationID   string            `json:"validation_id"`
	ReceiptSHA256  string            `json:"receipt_sha256"`
	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"`
	Limitations    []string          `json:"limitations,omitempty"`
	Incomplete     bool              `json:"incomplete,omitempty"`
}

type ExternalValidationReceipt 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            string            `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  string            `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"`
}

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

type HydrateOptions struct {
	Kind     string
	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 JUnitReportResult struct {
	Schema     string                `json:"schema"`
	RawSHA256  string                `json:"raw_sha256"`
	Total      int                   `json:"total"`
	Passed     int                   `json:"passed"`
	Failed     int                   `json:"failed"`
	Skipped    int                   `json:"skipped"`
	Errored    int                   `json:"errored"`
	Unknown    int                   `json:"unknown"`
	Incomplete bool                  `json:"incomplete"`
	ParseError string                `json:"parse_error,omitempty"`
	TestCases  []JUnitTestCaseResult `json:"test_cases,omitempty"`
}

type JUnitTestCaseResult struct {
	ID        string `json:"id,omitempty"`
	Name      string `json:"name,omitempty"`
	Classname string `json:"classname,omitempty"`
	Status    string `json:"status"`
}

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"`
	Total     int          `json:"total"`
	Truncated bool         `json:"truncated"`
}

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
	ReadOnly  bool
}

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

type ManifestExportOptions struct {
	WorkspaceID string
	PullRequest *ManifestPullRequestRef
}

type ManifestPullRequestRef struct {
	Owner  string
	Repo   string
	Number int
}

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"`
	SupportedSchemaVersion int64           `json:"supported_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
	ManifestID string
}

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

type PrepareReviewReportInput struct {
	OpportunityID string
	WorkspaceID   string
}

type PublishedDraftDifference struct {
	FirstDifferingLine int `json:"first_differing_line,omitempty"`
	DraftBytes         int `json:"draft_bytes"`
	PublishedBytes     int `json:"published_bytes"`
}

type PublishedDraftVerification struct {
	Status               string                    `json:"status"`
	DraftID              string                    `json:"draft_id"`
	Revision             int                       `json:"revision"`
	PublishedRef         string                    `json:"published_ref"`
	TitleComparison      string                    `json:"title_comparison,omitempty"`
	BodyComparison       string                    `json:"body_comparison,omitempty"`
	DraftTitleSHA256     string                    `json:"draft_title_sha256"`
	DraftBodySHA256      string                    `json:"draft_body_sha256"`
	PublishedTitleSHA256 string                    `json:"published_title_sha256,omitempty"`
	PublishedBodySHA256  string                    `json:"published_body_sha256,omitempty"`
	ObservedAt           string                    `json:"observed_at,omitempty"`
	SourceUpdatedAt      string                    `json:"source_updated_at,omitempty"`
	CoverageStatus       string                    `json:"coverage_status"`
	Difference           *PublishedDraftDifference `json:"difference,omitempty"`
	Reason               string                    `json:"reason,omitempty"`
}

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 RecordEvidenceInput struct {
	InvestigationID  string
	HypothesisID     string
	OpportunityID    string
	Type             string
	Relation         string
	Description      string
	SourceRefs       []domain.SourceRef
	SourceProvenance []evidence.SourceRevision
}

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

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

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

type RepositoryContextResult struct {
	Repo            RepoRef `json:"repo"`
	Requests        int     `json:"requests"`
	PlannedRequests int     `json:"planned_requests"`
	RequestBudget   int     `json:"request_budget"`
	Message         string  `json:"message"`
}

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

type ReviewReport struct {
	OpportunityID        string               `json:"opportunity_id,omitempty"`
	WorkspaceID          string               `json:"workspace_id,omitempty"`
	Repo                 RepoRef              `json:"repo"`
	OpportunityStatus    string               `json:"opportunity_status,omitempty"`
	CollisionStatus      string               `json:"collision_status,omitempty"`
	CollisionFindings    []evidence.Evidence  `json:"collision_findings"`
	DiffMetadata         *WorkspaceDiffResult `json:"diff_metadata,omitempty"`
	EvidenceSummary      EvidenceSummary      `json:"evidence_summary"`
	SuggestedReviewOrder []ReviewStep         `json:"suggested_review_order"`
	RenderedAt           time.Time            `json:"rendered_at"`
}

type ReviewStep struct {
	Path      string `json:"path"`
	Priority  int    `json:"priority"`
	Rationale string `json:"rationale"`
}

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 RuntimeContractResult struct {
	Name                   string `json:"name"`
	Version                string `json:"version"`
	SupportedSchemaLineage string `json:"supported_schema_lineage"`
	SupportedSchemaVersion int64  `json:"supported_schema_version"`
}

type RuntimeContractService interface {
	RuntimeContract(ctx context.Context) (*RuntimeContractResult, error)
}

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"`
	MatchSource    string   `json:"match_source,omitempty"`
	MatchExcerpt   string   `json:"match_excerpt,omitempty"`
	MatchTruncated bool     `json:"match_truncated,omitempty"`
}

type SearchOptions struct {
	Kind          string
	Repo          string
	State         string
	StateReason   string
	Merged        *bool
	Author        string
	Association   string
	Assignee      string
	Labels        []string
	UpdatedAfter  time.Time
	UpdatedBefore time.Time
	Limit         int
	Cursor        string
	Lens          string
	Sort          string
	MatchMode     string
	// SnapshotToken pins this read to one product-owned corpus state.
	SnapshotToken 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"`
	UnknownMergeCount    int           `json:"unknown_merge_count,omitempty"`
	SnapshotToken        string        `json:"snapshot_token"`
	ObservationWatermark int64         `json:"observation_watermark"`
}

type Service interface {
	Init(ctx context.Context) (*InitResult, error)
	Status(ctx context.Context) (*StatusResult, 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 SetupAuthentication struct {
	Method string `json:"method"`
	Key    string `json:"key,omitempty"`
}

type SetupClientDiscovery struct {
	Name       string
	Path       string
	Detected   bool
	Registered bool
	Error      string
}

type SetupDiscovery struct {
	Version               string
	Clients               []SetupClientDiscovery
	ConfiguredTokenSource string
	ConfiguredTokenKey    string
	GitHubCLIAvailable    bool
	EnvironmentKeyPresent bool
}

type SetupMCPCommand struct {
	Command string   `json:"command"`
	Args    []string `json:"args"`
}

type SetupMode string

type SetupObserver interface {
	SetupStarted(phase SetupPhase)
	SetupCompleted(step SetupStep)
}

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

	TokenSource    string
	TokenSourceKey string
	Repository     string
	DryRun         bool
	// Version is the release used for persistent CLI or private MCP runtime
	// installation. Empty values inherit the running service version.
	Version string
	// Executable is the packaged native program copied for MCP-only setup. It is
	// injectable so installation behavior can be tested without copying the test
	// process itself.
	Executable string
}

type SetupPhase string

type SetupReport struct {
	Operation         string                  `json:"operation"`
	DryRun            bool                    `json:"dry_run"`
	MCPCommand        *SetupMCPCommand        `json:"mcp_command,omitempty"`
	MCPCommandPending bool                    `json:"mcp_command_pending,omitempty"`
	RestartClients    []string                `json:"restart_clients,omitempty"`
	Authentication    *SetupAuthentication    `json:"authentication,omitempty"`
	Corpus            *CorpusInspectionResult `json:"corpus,omitempty"`
	Steps             []SetupStep             `json:"steps"`
}

type SetupService interface {
	DiscoverSetup(ctx context.Context) (*SetupDiscovery, error)
	Setup(ctx context.Context, opts SetupOptions) (*SetupReport, error)
	SetupWithProgress(ctx context.Context, opts SetupOptions, observer SetupObserver) (*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"`
	Total     int            `json:"total"`
	Truncated bool           `json:"truncated"`
}

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 SyncPlanResult struct {
	Repo                 RepoRef `json:"repo"`
	FixedRequests        int     `json:"fixed_requests"`
	ThreadRequestCeiling int     `json:"thread_request_ceiling"`
	PlannedRequests      int     `json:"planned_requests"`
	RequestBudget        int     `json:"request_budget"`
	MaxPages             int     `json:"max_pages"`
	ExactThreads         int     `json:"exact_threads"`
}

type SyncPlanningService interface {
	PlanRepositoryContextSync(ctx context.Context, repo RepoRef, maxRequests int) (*SyncPlanResult, error)
	PlanArchiveSync(ctx context.Context, repo RepoRef, opts ArchiveSyncOptions) (*SyncPlanResult, error)
}

type SyncResult struct {
	Repo            RepoRef         `json:"repo"`
	Threads         []SyncThreadRef `json:"threads,omitempty"`
	Updated         int             `json:"updated"`
	Requests        int             `json:"requests"`
	PlannedRequests int             `json:"planned_requests"`
	RequestBudget   int             `json:"request_budget"`
	Capped          bool            `json:"request_capped"`
	Message         string          `json:"message"`
}

type SyncThreadRef struct {
	Owner  string `json:"owner"`
	Repo   string `json:"repo"`
	Kind   string `json:"kind"`
	Number int    `json:"number"`
}

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 UpgradeConfiguredClient struct {
	Name    string `json:"name"`
	Path    string `json:"path,omitempty"`
	Version string `json:"version,omitempty"`
	Status  string `json:"status"`
	Message string `json:"message,omitempty"`
}

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"`
	Action            string                    `json:"action,omitempty"`
	Rollback          string                    `json:"rollback,omitempty"`
	RestartClients    []string                  `json:"restart_clients,omitempty"`
	Stages            []UpgradeStage            `json:"stages"`
	ConfiguredClients []UpgradeConfiguredClient `json:"configured_clients,omitempty"`
}

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

type UpgradeStage struct {
	Name    string `json:"name"`
	Status  string `json:"status"`
	Path    string `json:"path,omitempty"`
	Version string `json:"version,omitempty"`
	Target  string `json:"target,omitempty"`
	Message string `json:"message,omitempty"`
}

type ValidationAggregateResult struct {
	Kind                   string `json:"kind"`
	Requested              int    `json:"requested"`
	Completed              int    `json:"completed"`
	Passing                int    `json:"passing"`
	Failing                int    `json:"failing"`
	Inconclusive           int    `json:"inconclusive"`
	Cancelled              int    `json:"cancelled"`
	Classification         string `json:"classification"`
	ResourceClassification string `json:"resource_classification"`
}

type ValidationAttemptResult struct {
	Index             int                         `json:"index"`
	Kind              string                      `json:"kind"`
	RunID             string                      `json:"run_id,omitempty"`
	StartedAt         string                      `json:"started_at"`
	CompletedAt       string                      `json:"completed_at"`
	ExitCode          int                         `json:"exit_code"`
	Classification    string                      `json:"classification"`
	ObservationStatus string                      `json:"observation_status"`
	TimeoutPhase      string                      `json:"timeout_phase,omitempty"`
	FailurePhase      string                      `json:"failure_phase,omitempty"`
	Error             string                      `json:"error,omitempty"`
	Process           ValidationProcessIdentity   `json:"process"`
	Phases            ValidationRunPhases         `json:"phases"`
	Resources         ValidationResourceTelemetry `json:"resources"`
	Cleanup           ValidationCleanupResult     `json:"cleanup"`
}

type ValidationCleanupResult struct {
	Status    string                      `json:"status"`
	Reason    string                      `json:"reason,omitempty"`
	Survivors []ValidationProcessIdentity `json:"survivors,omitempty"`
	CheckedAt string                      `json:"checked_at,omitempty"`
}

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

type ValidationExpectedObservation struct {
	Name       string `json:"name"`
	Source     string `json:"source"`
	Matcher    string `json:"matcher"`
	Pattern    string `json:"pattern"`
	Occurrence string `json:"occurrence"`
	Path       string `json:"path,omitempty"`
}

type ValidationGroupComparisonResult struct {
	Classification string `json:"classification"`
	Explanation    string `json:"explanation"`
}

type ValidationInt64Metric struct {
	Value             *int64 `json:"value,omitempty"`
	UnavailableReason string `json:"unavailable_reason,omitempty"`
}

type ValidationObservationContract struct {
	Intent    string                          `json:"intent"`
	Base      []ValidationExpectedObservation `json:"base,omitempty"`
	Candidate []ValidationExpectedObservation `json:"candidate,omitempty"`
}

type ValidationObservationResult struct {
	ValidationExpectedObservation
	Status  string `json:"status"`
	Excerpt string `json:"excerpt,omitempty"`
	Error   string `json:"error,omitempty"`
}

type ValidationProcessIdentity struct {
	PID                 int32 `json:"pid,omitempty"`
	CreateTimeUnixMilli int64 `json:"create_time_unix_milli,omitempty"`
}

type ValidationReceiptService interface {
	AttachValidationReceipt(ctx context.Context, receipt ExternalValidationReceipt) (*ValidationRunResult, error)
}

type ValidationResourceTelemetry struct {
	Provider                   string                 `json:"provider"`
	Platform                   string                 `json:"platform"`
	SampleInterval             string                 `json:"sample_interval"`
	SampleCount                int                    `json:"sample_count"`
	CPUTimeMillis              ValidationInt64Metric  `json:"cpu_time_millis"`
	PeakRSSBytes               ValidationUint64Metric `json:"peak_rss_bytes"`
	PeakChildCount             ValidationInt64Metric  `json:"peak_child_count"`
	SamplerOverheadNanoseconds int64                  `json:"sampler_overhead_nanoseconds"`
}

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"`
	WorkspaceID          string                         `json:"workspace_id,omitempty"`
	BaseWorkspaceID      string                         `json:"base_workspace_id,omitempty"`
	CandidateWorkspaceID string                         `json:"candidate_workspace_id,omitempty"`
	Env                  []string                       `json:"environment_allowlist,omitempty"`
	Timeout              string                         `json:"timeout,omitempty"`
	MaxOutputBytes       int64                          `json:"max_output_bytes,omitempty"`
	Observation          *ValidationObservationContract `json:"observation,omitempty"`
	Protocol             string                         `json:"protocol,omitempty"`
	ReadinessTimeout     string                         `json:"readiness_timeout,omitempty"`
	CreatedAt            string                         `json:"created_at"`
}

type ValidationRunGroupResult struct {
	ID                  string                           `json:"id"`
	DefinitionID        string                           `json:"definition_id"`
	InvestigationID     string                           `json:"investigation_id"`
	ConfigurationSHA256 string                           `json:"configuration_sha256"`
	RequestedRuns       int                              `json:"requested_runs"`
	CompletedRuns       int                              `json:"completed_runs"`
	Concurrency         int                              `json:"concurrency"`
	PerRunTimeout       string                           `json:"per_run_timeout"`
	OverallTimeout      string                           `json:"overall_timeout"`
	SampleInterval      string                           `json:"sample_interval"`
	Attempts            []ValidationAttemptResult        `json:"attempts"`
	Aggregates          []ValidationAggregateResult      `json:"aggregates"`
	Classification      string                           `json:"classification"`
	Comparison          *ValidationGroupComparisonResult `json:"comparison,omitempty"`
	StartedAt           string                           `json:"started_at"`
	CompletedAt         string                           `json:"completed_at"`
}

type ValidationRunPhases struct {
	SpawnStartedAt    string `json:"spawn_started_at,omitempty"`
	ProcessStartedAt  string `json:"process_started_at,omitempty"`
	InitializedAt     string `json:"initialized_at,omitempty"`
	ToolsListedAt     string `json:"tools_listed_at,omitempty"`
	FirstResponseAt   string `json:"first_response_at,omitempty"`
	ExecutionEndedAt  string `json:"execution_ended_at,omitempty"`
	ShutdownStartedAt string `json:"shutdown_started_at,omitempty"`
	ShutdownCheckedAt string `json:"shutdown_checked_at,omitempty"`
}

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"`
	ObservationStatus       string                        `json:"observation_status"`
	Observations            []ValidationObservationResult `json:"observations,omitempty"`
	StartedAt               string                        `json:"started_at"`
	CompletedAt             string                        `json:"completed_at"`
	WorkspaceSnapshotBefore string                        `json:"workspace_snapshot_before,omitempty"`
	WorkspaceSnapshotAfter  string                        `json:"workspace_snapshot_after,omitempty"`
	WorkspaceBindingStatus  string                        `json:"workspace_binding_status,omitempty"`
	WorkspaceBindingReason  string                        `json:"workspace_binding_reason,omitempty"`
	Process                 ValidationProcessIdentity     `json:"process"`
	Phases                  ValidationRunPhases           `json:"phases"`
	TimeoutPhase            string                        `json:"timeout_phase,omitempty"`
	FailurePhase            string                        `json:"failure_phase,omitempty"`
	Resources               ValidationResourceTelemetry   `json:"resources"`
	Cleanup                 ValidationCleanupResult       `json:"cleanup"`
	ExecutionOrigin         string                        `json:"execution_origin,omitempty"`
	External                *ExternalValidationProvenance `json:"external,omitempty"`
	JUnitReport             *JUnitReportResult            `json:"junit_report,omitempty"`
}

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)
	RunValidationGroup(ctx context.Context, id string, opts RepeatValidationOptions) (*ValidationRunGroupResult, error)
	CompareValidation(ctx context.Context, baseRunID, candidateRunID string) (*ValidationComparisonResult, error)
}

type ValidationUint64Metric struct {
	Value             *uint64 `json:"value,omitempty"`
	UnavailableReason string  `json:"unavailable_reason,omitempty"`
}

type VerifyPublishedDraftInput struct {
	DraftID  string `json:"draft_id"`
	Revision int    `json:"revision"`
	Owner    string `json:"owner"`
	Repo     string `json:"repo"`
	Kind     string `json:"kind"`
	Number   int    `json:"number"`
}

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

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

type WorkflowService interface {
	UpdateHypothesisFields(ctx context.Context, id string, opts HypothesisUpdateOptions) (*investigation.Hypothesis, error)
	TransitionHypothesis(ctx context.Context, id, status, rationale string) (*investigation.Hypothesis, error)
	CheckHypothesisDuplicates(ctx context.Context, id string, limit int) (*DuplicateCheckResult, error)
	CheckOpportunityDuplicates(ctx context.Context, id string, limit int) (*DuplicateCheckResult, error)
	CheckHypothesisCollisions(ctx context.Context, id string, limit int) (*CollisionCheckResult, error)
	CheckOpportunityCollisions(ctx context.Context, id string, limit int) (*CollisionCheckResult, error)
	UpdateOpportunityCollisionStatus(ctx context.Context, id, status, rationale string) (*investigation.Opportunity, error)
	RecordEvidence(ctx context.Context, input RecordEvidenceInput) (*evidence.Evidence, error)
	WorkspaceDiff(ctx context.Context, id string) (*WorkspaceDiffResult, error)
	PrepareReviewReport(ctx context.Context, input PrepareReviewReportInput) (*ReviewReport, error)
}

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 WorkspaceAdoptOptions struct {
	Path    string
	BaseRef string
	Name    string
}

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

type WorkspaceDiffResult struct {
	ID               string       `json:"id"`
	Repo             RepoRef      `json:"repo"`
	BaseSHA          string       `json:"base_sha"`
	CandidateSHA     string       `json:"candidate_sha"`
	MergeBase        string       `json:"merge_base"`
	Dirty            bool         `json:"dirty"`
	HasUntracked     bool         `json:"has_untracked"`
	Diff             string       `json:"diff"`
	ChangedFiles     []string     `json:"changed_files"`
	ChangedFileCount int          `json:"changed_file_count"`
	DiffBytes        int          `json:"diff_bytes"`
	ReviewOrder      []ReviewStep `json:"review_order"`
}

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"`
	HasUntracked    bool    `json:"has_untracked"`
	Ownership       string  `json:"ownership"`
	CreatedAt       string  `json:"created_at"`
}

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