app

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2026 License: MIT Imports: 70 Imported by: 0

Documentation

Overview

Package app owns GitContribute use cases and capability composition.

Service methods are the shared application boundary for the CLI, MCP server, and terminal UI. Methods that read the corpus remain offline; methods that access GitHub, write local state, invoke git, or execute validation commands expose those effects explicitly. Product rules belong here rather than in a presentation adapter.

Index

Constants

View Source 
const (
	FacetIssueComments    = facets.IssueComments
	FacetPRDetails        = facets.PRDetails
	FacetPRReviews        = facets.PRReviews
	FacetPRReviewComments = facets.PRReviewComments
	FacetPRChecks         = facets.PRChecks
	FacetPRReviewThreads  = facets.PRReviewThreads
	FacetPRMergeState     = facets.PRMergeState
	FacetPRMergeQueue     = facets.PRMergeQueue
	FacetPRClosingIssues  = facets.PRClosingIssues
	FacetPRFiles          = facets.PRFiles
	FacetIssueTimeline    = facets.IssueTimeline
)

Thread facets that selective hydration can retrieve.

View Source 
const (
	// FacetContributionGuidance stores bounded repository contribution and AI policy documents.
	FacetContributionGuidance = "contribution_guidance"
)

Variables

View Source 
var ErrJobQueueFull = errors.New("job executor queue is full")

Functions

func NewRuntimeContract added in v0.9.0 

func NewRuntimeContract(version string) (*contracts.RuntimeContractResult, error)

NewRuntimeContract constructs immutable executable compatibility metadata. It does not resolve configuration, inspect a corpus, access the network, or write local state.

Types

type DuplicateCandidatesResult 

type DuplicateCandidatesResult struct {
	Repo           string     `json:"repo"`
	Kind           string     `json:"kind"`
	Number         int        `json:"number"`
	ClusterID      int64      `json:"cluster_id,omitempty"`
	StableID       string     `json:"stable_id,omitempty"`
	Canonical      ThreadRef  `json:"canonical,omitempty"`
	SourceRevision string     `json:"source_revision"`
	Limit          int        `json:"limit"`
	Total          int        `json:"total"`
	Candidates     []Neighbor `json:"candidates"`
}

DuplicateCandidatesResult is the response for a duplicate-candidate query.

type ExplainMatchResult 

type ExplainMatchResult struct {
	Score   float64  `json:"score"`
	Reasons []string `json:"reasons"`
}

ExplainMatchResult exposes the factual signals that contribute to a match score. It performs no network access.

type HydrateOptions 

type HydrateOptions struct {
	// Kind selects the exact issue or pull request when a number is ambiguous.
	Kind string
	// Facets lists the facets to retrieve. An empty list hydrates all facets
	// applicable to the thread kind.
	Facets []string
	// MaxPages bounds pagination per facet. Zero defaults to 50.
	MaxPages int
}

HydrateOptions controls selective thread hydration.

type HydrateRepositoryOptions 

type HydrateRepositoryOptions struct {
	Facets   []string
	MaxPages int
	State    string
	Numbers  []int
}

HydrateRepositoryOptions controls repository-wide thread hydration.

type HydrateResult 

type HydrateResult struct {
	Repo     contracts.RepoRef
	Number   int
	Kind     string
	Facets   []HydratedFacet
	Pages    int
	Requests int
	Capped   bool
	Message  string
}

HydrateResult reports the outcome of hydrating a thread.

type HydratedFacet 

type HydratedFacet struct {
	Facet    string
	Count    int
	Pages    int
	Complete bool
}

HydratedFacet reports coverage and counts for one hydrated facet.

type JobExecutor 

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

JobExecutor persists job records, runs work asynchronously in this process, and supports cancellation, progress recording, and safe shutdown. It does not replay interrupted host or network operations after restart.

Each executor registers a unique owner in the corpus and heartbeats while it is open. Startup only reconciles jobs whose owner is missing or has a stale heartbeat; live owners from other processes are never failed. One executor watcher polls admitted IDs together so cross-process cancellation stays prompt without one SQLite query loop per job.

func (*JobExecutor) Cancel 

func (e *JobExecutor) Cancel(ctx context.Context, id string) error

Cancel requests cancellation for a job. Queued jobs are marked cancelled immediately; running jobs have their context cancelled and finish as cancelled.

func (*JobExecutor) Close 

func (e *JobExecutor) Close() error

Close stops running and waiting jobs and waits for their goroutines.

func (*JobExecutor) Get 

func (e *JobExecutor) Get(ctx context.Context, id string) (*corpus.Job, error)

Get returns a job by opaque ID.

func (*JobExecutor) List 

func (e *JobExecutor) List(ctx context.Context, status string, limit int) ([]corpus.Job, error)

List returns recent jobs, optionally filtered by status.

func (*JobExecutor) Submit 

func (e *JobExecutor) Submit(ctx context.Context, kind string, request any, fn JobFunc) (string, error)

Submit persists a queued job and runs it asynchronously.

type JobFunc 

type JobFunc func(ctx context.Context, report func(progress, statistics string) error) (any, error)

JobFunc performs asynchronous work for a job. It receives a context that is cancelled when the job is cancelled or the executor closes, and a report callback that records progress and statistics in the corpus.

type MCPReader 

type MCPReader struct{ *Service }

MCPReader adapts Service to the mcpcontract.Reader interface. It is a thin wrapper because Go does not allow two methods named Search on one type.

func (*MCPReader) ActorResource added in v1.0.0 

func (r *MCPReader) ActorResource(ctx context.Context, ref, facet string) (any, error)

ActorResource returns the canonical stored actor view without refreshing it.

func (*MCPReader) AdoptWorkspace added in v0.10.0 

func (r *MCPReader) AdoptWorkspace(ctx context.Context, in mcpcontract.AdoptWorkspaceInput) (mcpcontract.AdoptWorkspaceOutput, error)

AdoptWorkspace records an existing worktree synchronously without exposing its host path or remote URL in the protocol result.

func (*MCPReader) AttachJUnitReport added in v1.1.0 

func (r *MCPReader) AttachJUnitReport(ctx context.Context, in mcpcontract.AttachJUnitReportInput) (mcpcontract.AttachJUnitReportOutput, error)

func (*MCPReader) AttachValidationReceipt added in v0.14.0 

func (r *MCPReader) AttachValidationReceipt(ctx context.Context, in mcpcontract.AttachValidationReceiptInput) (mcpcontract.ExternalValidationReceiptOutput, error)

func (*MCPReader) BuildRepositoryDossier 

func (r *MCPReader) BuildRepositoryDossier(ctx context.Context, in mcpcontract.BuildRepositoryDossierInput) (mcpcontract.JobReference, error)

BuildRepositoryDossier submits a durable job that builds a repository dossier.

func (*MCPReader) CIFailureResource added in v0.16.0 

func (r *MCPReader) CIFailureResource(ctx context.Context, owner, repo string, number int) (map[string]any, error)

func (*MCPReader) CIJobLogResource added in v0.16.0 

func (r *MCPReader) CIJobLogResource(ctx context.Context, owner, repo string, number int, jobID int64) (map[string]any, error)

func (*MCPReader) CancelJobs added in v0.6.0 

func (r *MCPReader) CancelJobs(ctx context.Context, in mcpcontract.CancelJobInput) (mcpcontract.GetJobsOutput, error)

CancelJobs requests bounded cancellation in input order. Missing and terminal jobs remain item-level outcomes so one bad ID does not hide successful writes.

func (*MCPReader) CheckCollisions 

func (r *MCPReader) CheckCollisions(ctx context.Context, in mcpcontract.CheckCollisionsInput) (mcpcontract.CheckOutput, error)

CheckCollisions finds open pull request collisions for a hypothesis or opportunity.

func (*MCPReader) CheckDuplicates 

func (r *MCPReader) CheckDuplicates(ctx context.Context, in mcpcontract.CheckDuplicatesInput) (mcpcontract.CheckOutput, error)

CheckDuplicates finds duplicate-candidate threads for a hypothesis or opportunity.

func (*MCPReader) CheckMergeConflicts added in v0.5.0 

func (r *MCPReader) CheckMergeConflicts(ctx context.Context, in mcpcontract.CheckMergeConflictsInput) (mcpcontract.CheckMergeConflictsOutput, error)

CheckMergeConflicts compares already-fetched OIDs in managed workspaces without fetching or modifying refs, indexes, or worktrees.

func (*MCPReader) CodeIndexArtifact added in v0.17.0 

func (r *MCPReader) CodeIndexArtifact(ctx context.Context, digest string) (mcpcontract.CodeIndexArtifact, error)

CodeIndexArtifact resolves only an immutable digest-bound record. Missing or inconsistent records never fall back to the latest repository projection.

func (*MCPReader) Concern added in v0.15.0 

func (r *MCPReader) Concern(ctx context.Context, in mcpcontract.ConcernInput) (mcpcontract.ConcernOutput, error)

Concern reads one persisted concern without external access.

func (*MCPReader) CreateConcern added in v0.10.0 

func (r *MCPReader) CreateConcern(ctx context.Context, in mcpcontract.CreateConcernInput) (mcpcontract.ConcernOutput, error)

CreateConcern implements the MCP local concern-write capability.

func (*MCPReader) CreateWorkspace 

func (r *MCPReader) CreateWorkspace(ctx context.Context, in mcpcontract.CreateWorkspaceInput) (mcpcontract.JobReference, error)

CreateWorkspace submits a durable job that clones a remote and creates a worktree.

func (*MCPReader) DeepWiki added in v0.5.0 

func (r *MCPReader) DeepWiki(ctx context.Context, in mcpcontract.DeepWikiInput) (mcpcontract.DeepWikiOutput, error)

DeepWiki performs one external derived-knowledge read and does not persist its response.

func (*MCPReader) DefineValidation 

func (r *MCPReader) DefineValidation(ctx context.Context, in mcpcontract.DefineValidationInput) (mcpcontract.ValidationOutput, error)

DefineValidation stores a validation definition.

func (*MCPReader) Dossier 

func (r *MCPReader) Dossier(ctx context.Context, in mcpcontract.RepoInput) (mcpcontract.DossierOutput, error)

Dossier returns the latest persisted source-backed repository dossier.

func (*MCPReader) Draft added in v0.15.0 

func (r *MCPReader) Draft(ctx context.Context, in mcpcontract.DraftInput) (mcpcontract.DraftOutput, error)

Draft reads one immutable persisted contribution-draft revision.

func (*MCPReader) EnsureCoverage added in v0.17.0 

func (r *MCPReader) EnsureCoverage(ctx context.Context, in mcpcontract.EnsureCoverageInput) (mcpcontract.JobReference, error)

EnsureCoverage submits one durable workflow that owns repository bootstrap, header synchronization, selected facet hydration, verification, and an immutable offline handoff.

func (*MCPReader) Evidence 

func (r *MCPReader) Evidence(ctx context.Context, in mcpcontract.EvidenceInput) (mcpcontract.EvidenceOutput, error)

Evidence reads evidence for a local investigation or opportunity.

func (*MCPReader) ExplainMatch 

func (r *MCPReader) ExplainMatch(ctx context.Context, in mcpcontract.ExplainMatchInput) (mcpcontract.ExplainMatchOutput, error)

ExplainMatch explains why a search result matched.

func (*MCPReader) ExportManifest added in v0.10.0 

func (r *MCPReader) ExportManifest(ctx context.Context, in mcpcontract.ExportManifestInput) (mcpcontract.ManifestOutput, error)

ExportManifest assembles a bounded local contribution evidence statement.

func (*MCPReader) FindClusters 

func (r *MCPReader) FindClusters(ctx context.Context, in mcpcontract.FindClustersInput) (mcpcontract.FindClustersOutput, error)

FindClusters lists duplicate-candidate clusters for bounded repository targets from the local corpus without recomputing them.

func (*MCPReader) FindNeighbors 

func (r *MCPReader) FindNeighbors(ctx context.Context, in mcpcontract.FindNeighborsInput) (mcpcontract.FindNeighborsOutput, error)

FindNeighbors ranks similar local threads in input order without network access.

func (*MCPReader) FindPortfolioOverlaps added in v0.6.0 

func (r *MCPReader) FindPortfolioOverlaps(ctx context.Context, in mcpcontract.FindPortfolioOverlapsInput) (mcpcontract.FindPortfolioOverlapsOutput, error)

FindPortfolioOverlaps is a pure corpus read over complete normalized signal snapshots. It preserves candidate order and never treats absent coverage as proof that no overlap exists.

func (*MCPReader) FindPrecedents added in v0.5.0 

func (r *MCPReader) FindPrecedents(ctx context.Context, in mcpcontract.FindPrecedentsInput) (mcpcontract.FindPrecedentsOutput, error)

FindPrecedents performs an offline similarity search over stored resolved threads. Each source thread is resolved and ranked independently while preserving input order and item-level recovery guidance in the bounded batch response.

func (*MCPReader) GetActorFacets added in v1.0.0 

func (r *MCPReader) GetActorFacets(ctx context.Context, in mcpcontract.GetActorFacetsInput) (mcpcontract.GetActorFacetsOutput, error)

GetActorFacets reads local facet coverage and returns opaque resource URIs.

func (*MCPReader) GetActors added in v1.0.0 

func (r *MCPReader) GetActors(ctx context.Context, in mcpcontract.GetActorsInput) (mcpcontract.GetActorsOutput, error)

GetActors performs an input-ordered local actor read.

func (*MCPReader) GetCoverage 

func (r *MCPReader) GetCoverage(ctx context.Context, in mcpcontract.GetCoverageInput) (mcpcontract.GetCoverageOutput, error)

GetCoverage returns bounded, input-ordered facet coverage without network access.

func (*MCPReader) GetFixPatternReport added in v0.14.0 

func (r *MCPReader) GetFixPatternReport(ctx context.Context, id string) (mcpcontract.FixPatternReport, error)

GetFixPatternReport reads the typed terminal result of a pattern-mining job.

func (*MCPReader) GetJob 

func (r *MCPReader) GetJob(ctx context.Context, in mcpcontract.GetJobInput) (mcpcontract.GetJobOutput, error)

GetJob reads a durable job by ID.

func (*MCPReader) GetJobs added in v0.5.0 

func (r *MCPReader) GetJobs(ctx context.Context, in mcpcontract.GetJobsInput) (mcpcontract.GetJobsOutput, error)

GetJobs reads up to 100 durable job records without waiting for completion.

func (*MCPReader) GetRepositories added in v0.5.0 

func (r *MCPReader) GetRepositories(ctx context.Context, in mcpcontract.GetRepositoriesInput) (mcpcontract.GetRepositoriesOutput, error)

GetRepositories performs an offline, input-ordered corpus read and clears repository facts when metadata coverage has not been observed.

func (*MCPReader) GetThreadFacets added in v0.17.0 

func (r *MCPReader) GetThreadFacets(ctx context.Context, in mcpcontract.GetThreadFacetsInput) (mcpcontract.GetThreadFacetsOutput, error)

GetThreadFacets reads bounded facet coverage and resource identities from the local corpus. It never decodes or fetches large payloads in the tool result.

func (*MCPReader) GetThreads added in v0.5.0 

func (r *MCPReader) GetThreads(ctx context.Context, in mcpcontract.GetThreadsInput) (mcpcontract.GetThreadsOutput, error)

GetThreads performs an offline, input-ordered exact-thread read. Compact mode omits bodies to keep broad triage responses bounded.

func (*MCPReader) HydrateThreads added in v0.5.0 

func (r *MCPReader) HydrateThreads(ctx context.Context, in mcpcontract.HydrateThreadsInput) (mcpcontract.JobReference, error)

HydrateThreads submits a durable GitHub read for explicit child facets on selected threads; an empty facet set is rejected.

func (*MCPReader) ImportExternalEvidenceManifest added in v1.1.0 

func (r *MCPReader) ImportExternalEvidenceManifest(ctx context.Context, in mcpcontract.ImportExternalEvidenceManifestInput) (mcpcontract.ImportExternalEvidenceManifestOutput, error)

func (*MCPReader) IndexPullRequestFeedback added in v0.19.0 

func (r *MCPReader) IndexPullRequestFeedback(ctx context.Context, in mcpcontract.IndexPullRequestFeedbackInput) (mcpcontract.JobReference, error)

IndexPullRequestFeedback submits a repository-scoped durable discovery and feedback job. Repeating the same repository resumes its stored provider page when the previous run was bounded or interrupted.

func (*MCPReader) IndexRepositories added in v0.5.0 

func (r *MCPReader) IndexRepositories(ctx context.Context, in mcpcontract.IndexRepositoriesInput) (mcpcontract.JobReference, error)

IndexRepositories submits a durable Git acquisition and safe indexing job with at most two repositories processed concurrently.

func (*MCPReader) InspectCommitChanges added in v0.10.0 

func (r *MCPReader) InspectCommitChanges(ctx context.Context, in mcpcontract.InspectCommitChangesInput) (mcpcontract.CommitInventoryOutput, error)

InspectCommitChanges implements the MCP commit-inventory capability.

func (*MCPReader) Investigation 

func (r *MCPReader) Investigation(ctx context.Context, in mcpcontract.InvestigationInput) (mcpcontract.InvestigationOutput, error)

Investigation reads a local investigation workspace from the corpus.

func (*MCPReader) Lens 

func (r *MCPReader) Lens(ctx context.Context, in mcpcontract.LensInput) (mcpcontract.LensOutput, error)

Lens reads a saved lens definition from the local corpus.

func (*MCPReader) LinkConcern added in v0.10.0 

func (r *MCPReader) LinkConcern(ctx context.Context, in mcpcontract.LinkConcernInput) (mcpcontract.ConcernOutput, error)

LinkConcern implements MCP concern relationship writes.

func (*MCPReader) LinkPullRequest added in v0.6.0 

func (r *MCPReader) LinkPullRequest(ctx context.Context, in mcpcontract.LinkPullRequestInput) (mcpcontract.LinkPullRequestOutput, error)

LinkPullRequest records an explicit local relationship without mutating GitHub.

func (*MCPReader) ListConcerns added in v0.10.0 

func (r *MCPReader) ListConcerns(ctx context.Context, in mcpcontract.ListConcernsInput) (mcpcontract.ConcernListOutput, error)

ListConcerns implements the MCP offline concern-read capability.

func (*MCPReader) ListOpportunities 

func (r *MCPReader) ListOpportunities(ctx context.Context, in mcpcontract.ListOpportunitiesInput) (mcpcontract.ListOpportunitiesOutput, error)

ListOpportunities lists opportunities for a local investigation.

func (*MCPReader) ListPullRequestPortfolio added in v0.5.0 

func (r *MCPReader) ListPullRequestPortfolio(ctx context.Context, in mcpcontract.ListPullRequestPortfolioInput) (mcpcontract.ListPullRequestPortfolioOutput, error)

ListPullRequestPortfolio performs an offline projection over stored authored PRs and status facets; unsupported health facets remain explicitly unknown.

func (*MCPReader) Manifest added in v0.15.0 

func (r *MCPReader) Manifest(ctx context.Context, in mcpcontract.ManifestInput) (mcpcontract.ManifestOutput, error)

Manifest reads one persisted contribution evidence manifest.

func (*MCPReader) MineRepositoryFixPatterns added in v0.14.0 

func (r *MCPReader) MineRepositoryFixPatterns(ctx context.Context, in mcpcontract.MineRepositoryFixPatternsInput) (mcpcontract.JobReference, error)

MineRepositoryFixPatterns submits one bounded GitHub-read/local-write workflow. It searches stored candidates first and hydrates only finalists whose merge outcome is unknown.

func (*MCPReader) Opportunity 

func (r *MCPReader) Opportunity(ctx context.Context, in mcpcontract.OpportunityInput) (mcpcontract.OpportunityOutput, error)

Opportunity reads a local contribution opportunity.

func (*MCPReader) PlanSemanticCommits added in v0.10.0 

func (r *MCPReader) PlanSemanticCommits(ctx context.Context, in mcpcontract.PlanSemanticCommitsInput) (mcpcontract.SemanticCommitPlanOutput, error)

PlanSemanticCommits implements the MCP read-only semantic planning capability.

func (*MCPReader) PreflightContribution added in v0.19.0 

func (r *MCPReader) PreflightContribution(ctx context.Context, in mcpcontract.ContributionPreflightInput) (mcpcontract.ContributionPreflightOutput, error)

PreflightContribution performs the bounded, side-effect-free routing check described by workflow.preflight_contribution. Unlike portfolio sync, it does not write observations, create jobs, create worktrees, or adopt paths.

func (*MCPReader) PrepareContribution 

func (r *MCPReader) PrepareContribution(ctx context.Context, in mcpcontract.PrepareContributionInput) (mcpcontract.DraftOutput, error)

PrepareContribution renders a contribution draft for an opportunity.

func (*MCPReader) PrepareIssueSet added in v0.12.0 

func (r *MCPReader) PrepareIssueSet(ctx context.Context, in mcpcontract.PrepareIssueSetInput) (mcpcontract.PrepareIssueSetOutput, error)

PrepareIssueSet composes contribution-facing evidence for exact stored issues. It opens only the read-only corpus and never creates workflow state.

func (*MCPReader) PreviewRepositoryFixPatterns added in v0.17.0 

func (r *MCPReader) PreviewRepositoryFixPatterns(ctx context.Context, in mcpcontract.PreviewRepositoryFixPatternsInput) (mcpcontract.FixPatternReport, error)

PreviewRepositoryFixPatterns performs the same bounded corpus analysis as the durable workflow while keeping the entire operation read-only. Preview deliberately disables hydration: it is an offline planning read, not a hidden synchronization request.

func (*MCPReader) PromoteConcern added in v0.10.0 

func (r *MCPReader) PromoteConcern(ctx context.Context, in mcpcontract.PromoteConcernInput) (mcpcontract.ConcernOutput, error)

PromoteConcern implements atomic MCP concern promotion.

func (*MCPReader) PromoteOpportunity 

func (r *MCPReader) PromoteOpportunity(ctx context.Context, in mcpcontract.PromoteOpportunityInput) (mcpcontract.OpportunityOutput, error)

PromoteOpportunity promotes a hypothesis to an opportunity.

func (*MCPReader) PullRequestFeedbackItemResource added in v1.0.0 

func (r *MCPReader) PullRequestFeedbackItemResource(ctx context.Context, owner, repo string, number int, channel, feedbackID string) (map[string]any, error)

PullRequestFeedbackItemResource returns the exact normalized record named by a search match. The root feedback resource remains the canonical raw facet view; this child resource is the compact, identity-preserving follow-up.

func (*MCPReader) PullRequestFeedbackResource added in v0.16.0 

func (r *MCPReader) PullRequestFeedbackResource(ctx context.Context, owner, repo string, number int) (map[string]any, error)

func (*MCPReader) RankOpportunities added in v0.5.0 

func (r *MCPReader) RankOpportunities(ctx context.Context, in mcpcontract.RankOpportunitiesInput) (mcpcontract.RankOpportunitiesOutput, error)

RankOpportunities performs deterministic offline Radar ranking across stored repositories.

func (*MCPReader) ReadGitHubThreadSearchArtifact added in v0.18.0 

func (r *MCPReader) ReadGitHubThreadSearchArtifact(ctx context.Context, digest string) (mcpcontract.GitHubThreadSearchArtifact, error)

ReadGitHubThreadSearchArtifact is a local-only typed resource reader.

func (*MCPReader) ReadSnapshot added in v0.17.0 

func (r *MCPReader) ReadSnapshot(ctx context.Context, token string) (mcpcontract.CorpusSnapshotArtifact, error)

func (*MCPReader) ReadSourceBundleArtifact added in v0.18.0 

func (r *MCPReader) ReadSourceBundleArtifact(ctx context.Context, digest string) (mcpcontract.SourceBundleArtifact, error)

ReadSourceBundleArtifact is a local-only typed resource reader.

func (*MCPReader) ReadSourceFiles added in v0.18.0 

func (r *MCPReader) ReadSourceFiles(ctx context.Context, in mcpcontract.ReadSourceFilesInput) (mcpcontract.ReadSourceFilesOutput, error)

ReadSourceFiles performs bounded live source acquisition and stores only the resulting immutable source bundle. It does not touch thread facets or code index projections.

func (*MCPReader) Readiness 

func (r *MCPReader) Readiness(ctx context.Context, in mcpcontract.ReadinessInput) (mcpcontract.ReadinessOutput, error)

Readiness reads a local contribution readiness report through MCP.

func (*MCPReader) RecordHypothesis 

func (r *MCPReader) RecordHypothesis(ctx context.Context, in mcpcontract.RecordHypothesisInput) (mcpcontract.HypothesisOutput, error)

RecordHypothesis records a fully structured hypothesis.

func (*MCPReader) Repository 

func (r *MCPReader) Repository(ctx context.Context, in mcpcontract.RepoInput) (mcpcontract.RepositoryOutput, error)

Repository reads a repository projection from the local corpus.

func (*MCPReader) RunValidation 

func (r *MCPReader) RunValidation(ctx context.Context, in mcpcontract.RunValidationInput) (mcpcontract.JobReference, error)

RunValidation submits one bounded validation execution group.

func (*MCPReader) Search 

func (r *MCPReader) Search(ctx context.Context, in mcpcontract.SearchInput) (mcpcontract.SearchOutput, error)

Search performs a local-only corpus search through the MCP interface.

func (*MCPReader) SearchActors added in v1.0.0 

func (r *MCPReader) SearchActors(ctx context.Context, in mcpcontract.SearchActorsInput) (mcpcontract.SearchActorsOutput, error)

SearchActors is a local-only actor search.

func (*MCPReader) SearchCode 

func (r *MCPReader) SearchCode(ctx context.Context, in mcpcontract.SearchCodeInput) (mcpcontract.SearchCodeOutput, error)

SearchCode searches indexed code snapshots in the local corpus.

func (*MCPReader) SearchCodeBatch added in v0.18.0 

func (r *MCPReader) SearchCodeBatch(ctx context.Context, in mcpcontract.SearchCodeBatchInput) (mcpcontract.SearchCodeBatchOutput, error)

SearchCodeBatch performs ordered offline code searches over one shared corpus revision. Each query keeps the single-query coverage and truncation semantics; the tool only removes the model-side fan-out loop.

func (*MCPReader) SearchContributions added in v1.0.0 

func (r *MCPReader) SearchContributions(ctx context.Context, in mcpcontract.SearchContributionsInput) (mcpcontract.SearchContributionsOutput, error)

SearchContributions reads contribution observations from the local corpus.

func (*MCPReader) SearchGitHubRepositories added in v0.5.0 

func (r *MCPReader) SearchGitHubRepositories(ctx context.Context, in mcpcontract.SearchGitHubRepositoriesInput) (mcpcontract.SearchGitHubRepositoriesOutput, error)

SearchGitHubRepositories performs one bounded live repository search and persists the returned metadata observations without fetching thread data.

func (*MCPReader) SearchGitHubThreads added in v0.18.0 

func (r *MCPReader) SearchGitHubThreads(ctx context.Context, in mcpcontract.SearchGitHubThreadsInput) (mcpcontract.SearchGitHubThreadsOutput, error)

SearchGitHubThreads performs one bounded live issue-search request, records returned thread observations, and creates an immutable query-result artifact. It never claims repository-wide thread coverage.

func (*MCPReader) SearchGitHubUsers added in v1.0.0 

func (r *MCPReader) SearchGitHubUsers(ctx context.Context, in mcpcontract.SearchGitHubUsersInput) (mcpcontract.SearchGitHubUsersOutput, error)

SearchGitHubUsers performs one bounded live discovery page and persists only identity observations; it never expands the result into N profile reads.

func (*MCPReader) SearchPullRequestFeedback added in v0.19.0 

func (r *MCPReader) SearchPullRequestFeedback(ctx context.Context, in mcpcontract.SearchPullRequestFeedbackInput) (mcpcontract.SearchPullRequestFeedbackOutput, error)

SearchPullRequestFeedback is an offline read over the repository feedback projection. Coverage state is returned independently from match count.

func (*MCPReader) SearchRepositories 

func (r *MCPReader) SearchRepositories(ctx context.Context, in mcpcontract.SearchRepositoriesInput) (mcpcontract.SearchRepositoriesOutput, error)

SearchRepositories performs a local-only repository search.

func (*MCPReader) SetConcernStatus added in v0.10.0 

func (r *MCPReader) SetConcernStatus(ctx context.Context, in mcpcontract.SetConcernStatusInput) (mcpcontract.ConcernOutput, error)

SetConcernStatus implements MCP concern lifecycle transitions.

func (*MCPReader) StartInvestigation 

func (r *MCPReader) StartInvestigation(ctx context.Context, in mcpcontract.StartInvestigationInput) (mcpcontract.InvestigationOutput, error)

RunValidation submits a durable validation run. StartInvestigation creates a new investigation workspace.

func (*MCPReader) SyncCIFailures added in v0.16.0 

func (r *MCPReader) SyncCIFailures(ctx context.Context, in mcpcontract.SyncCIFailuresInput) (mcpcontract.JobReference, error)

func (*MCPReader) SyncPortfolio added in v0.14.0 

func (r *MCPReader) SyncPortfolio(ctx context.Context, in mcpcontract.SyncPortfolioInput) (mcpcontract.JobReference, error)

SyncPortfolio submits one bounded job that discovers pull requests authored by the active credential and refreshes health for the resulting stored set.

func (*MCPReader) SyncPullRequestFeedback added in v0.16.0 

func (r *MCPReader) SyncPullRequestFeedback(ctx context.Context, in mcpcontract.SyncPullRequestFeedbackInput) (mcpcontract.JobReference, error)

func (*MCPReader) SyncRepositoryContext added in v0.13.0 

func (r *MCPReader) SyncRepositoryContext(ctx context.Context, in mcpcontract.SyncRepositoryContextInput) (mcpcontract.JobReference, error)

SyncRepositoryContext submits a durable metadata and contribution-guidance GitHub read. It does not fetch threads, comments, reviews, or code.

func (*MCPReader) SyncThreads added in v0.5.0 

func (r *MCPReader) SyncThreads(ctx context.Context, in mcpcontract.SyncThreadsInput) (mcpcontract.JobReference, error)

SyncThreads submits a durable bounded GitHub read for thread headers in repositories that already have local identities.

func (*MCPReader) SyncUserContributions added in v1.0.0 

func (r *MCPReader) SyncUserContributions(ctx context.Context, in mcpcontract.SyncUserContributionsInput) (mcpcontract.JobReference, error)

SyncUserContributions maps GitHub's typed contribution union into independently queryable corpus rows. Keeping the mapping together makes its atomic replacement boundary visible.

func (*MCPReader) SyncUserOrganizations added in v1.0.0 

func (r *MCPReader) SyncUserOrganizations(ctx context.Context, in mcpcontract.SyncUserFacetInput) (mcpcontract.JobReference, error)

func (*MCPReader) SyncUserPinnedItems added in v1.0.0 

func (r *MCPReader) SyncUserPinnedItems(ctx context.Context, in mcpcontract.SyncUserPinnedItemsInput) (mcpcontract.JobReference, error)

func (*MCPReader) SyncUserRepositories added in v1.0.0 

func (r *MCPReader) SyncUserRepositories(ctx context.Context, in mcpcontract.SyncUserRepositoriesInput) (mcpcontract.JobReference, error)

func (*MCPReader) SyncUserSocialAccounts added in v1.0.0 

func (r *MCPReader) SyncUserSocialAccounts(ctx context.Context, in mcpcontract.SyncUserFacetInput) (mcpcontract.JobReference, error)

func (*MCPReader) SyncUsers added in v1.0.0 

func (r *MCPReader) SyncUsers(ctx context.Context, in mcpcontract.SyncUsersInput) (mcpcontract.JobReference, error)

SyncUsers submits a durable exact-profile acquisition batch.

func (*MCPReader) Thread 

func (r *MCPReader) Thread(ctx context.Context, in mcpcontract.ThreadInput) (mcpcontract.ThreadOutput, error)

Thread reads one issue or pull request from the local corpus.

func (*MCPReader) ThreadByNumber 

func (r *MCPReader) ThreadByNumber(ctx context.Context, in mcpcontract.ThreadByNumberInput) (mcpcontract.ThreadOutput, error)

ThreadByNumber reads an issue or pull request by repository and number only.

func (*MCPReader) ThreadFacetResource added in v0.17.0 

func (r *MCPReader) ThreadFacetResource(ctx context.Context, owner, repo, kind string, number int, facet string) (map[string]any, error)

ThreadFacetResource is the canonical offline payload read for one stored facet. Resource reads are intentionally separate from bounded tool output.

func (*MCPReader) UpdateConcern added in v0.10.0 

func (r *MCPReader) UpdateConcern(ctx context.Context, in mcpcontract.UpdateConcernInput) (mcpcontract.ConcernOutput, error)

UpdateConcern implements MCP concern content updates.

func (*MCPReader) VerifyPublishedDraft added in v0.14.0 

func (r *MCPReader) VerifyPublishedDraft(ctx context.Context, in mcpcontract.VerifyPublishedDraftInput) (mcpcontract.PublishedDraftVerificationOutput, error)

func (*MCPReader) WaitPullRequestChecks added in v1.1.0 

func (r *MCPReader) WaitPullRequestChecks(ctx context.Context, in mcpcontract.WaitPullRequestChecksInput) (mcpcontract.JobReference, error)

WaitPullRequestChecks owns the unchanged-state interval inside a durable job. It watches one exact head and only replaces the stored health snapshot after a complete terminal observation, so timeout/cancellation cannot erase the last usable corpus projection.

func (*MCPReader) Workspace added in v0.16.0 

func (r *MCPReader) Workspace(ctx context.Context, id string) (mcpcontract.WorkspaceResource, error)

Workspace returns a host-path-free workspace projection for offline resource reads.

type ManifestOptions added in v0.10.0 

type ManifestOptions struct {
	WorkspaceID   string
	PullRequest   *ManifestPullRequest
	SnapshotToken string
}

ManifestOptions selects optional local workspace and exact stored PR inputs.

type ManifestPullRequest added in v0.10.0 

type ManifestPullRequest struct {
	Owner  string
	Repo   string
	Number int
}

ManifestPullRequest identifies one exact stored pull request.

type Neighbor 

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

Neighbor is one ranked thread near a query.

type NeighborsResult 

type NeighborsResult struct {
	Repo           string                 `json:"repo"`
	Kind           string                 `json:"kind"`
	Number         int                    `json:"number"`
	Limit          int                    `json:"limit"`
	Total          int                    `json:"total"`
	SourceRevision string                 `json:"source_revision"`
	RuleVersion    similarity.RuleVersion `json:"rule_version"`
	Neighbors      []Neighbor             `json:"neighbors"`
}

NeighborsResult is the response for a local nearest-thread query.

type PullRequestCollision 

type PullRequestCollision struct {
	Number  int     `json:"number"`
	Title   string  `json:"title"`
	Author  string  `json:"author"`
	BaseRef string  `json:"base_ref"`
	Score   float64 `json:"score"`
	Reason  string  `json:"reason"`
}

PullRequestCollision is a competing open pull request with a score and reason.

type PullRequestCollisionResult 

type PullRequestCollisionResult struct {
	Repo             string                 `json:"repo"`
	Number           int                    `json:"number"`
	Limit            int                    `json:"limit"`
	Total            int                    `json:"total"`
	Truncated        bool                   `json:"truncated"`
	Population       int                    `json:"population"`
	PopulationCapped bool                   `json:"population_capped"`
	SourceRevision   string                 `json:"source_revision"`
	Collisions       []PullRequestCollision `json:"collisions"`
}

PullRequestCollisionResult is the response for a focused open-PR collision query.

type Service 

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

func New 

func New(paths *config.Paths, version string, logger *slog.Logger) (*Service, error)

New creates a Service and resolves local configuration. GitHub credentials are resolved lazily only when a network-reading operation is requested.

func NewWithContext added in v0.8.0 

func NewWithContext(ctx context.Context, paths *config.Paths, version string, logger *slog.Logger) (*Service, error)

NewWithContext creates a Service bounded by ctx and Close.

func (*Service) Acquire 

func (s *Service) Acquire(ctx context.Context, repo contracts.RepoRef, remote string) (result *contracts.AcquisitionResult, returnErr error)

Acquire clones or fetches a repository into the managed cache, records the resolved remote URL/default branch/commit SHA/acquired time, and indexes the clean checkout into the corpus. It does not execute repository code.

func (*Service) Actions added in v0.14.0 

func (s *Service) Actions(_ context.Context, item tuicontract.Item) ([]tuicontract.Action, error)

Actions returns only parameter-free operations that the application can execute for the selected item today.

func (*Service) AddCollectionMembers 

func (s *Service) AddCollectionMembers(ctx context.Context, name string, members []contracts.CollectionMember) (*contracts.CollectionResult, error)

AddCollectionMembers idempotently adds typed references to a collection.

func (*Service) AddGHArchiveSource 

func (s *Service) AddGHArchiveSource(ctx context.Context, name string, events []string) (*contracts.SourceResult, error)

AddGHArchiveSource stores a named GH Archive event filter without fetching data.

func (*Service) AddHypothesis 

func (s *Service) AddHypothesis(ctx context.Context, investigationID, title, description, category string) (*contracts.HypothesisResult, error)

AddHypothesis records a hypothesis under an investigation.

func (*Service) AddLens 

func (s *Service) AddLens(ctx context.Context, name string, def lens.Definition) (*contracts.LensResult, error)

AddLens validates and stores a lens definition.

func (*Service) AddRepoSource 

func (s *Service) AddRepoSource(ctx context.Context, name string, refs []contracts.RepoRef) (*contracts.SourceResult, error)

AddRepoSource stores a named, explicit set of repositories without fetching them.

func (*Service) AddSearchSource 

func (s *Service) AddSearchSource(ctx context.Context, name, query string) (*contracts.SourceResult, error)

AddSearchSource stores a named GitHub repository-search source without executing it.

func (*Service) AdoptWorkspace added in v0.10.0 

func (s *Service) AdoptWorkspace(ctx context.Context, investigationID string, opts contracts.WorkspaceAdoptOptions) (*contracts.WorkspaceResult, error)

AdoptWorkspace records an existing local worktree without fetching, changing its refs, or taking ownership of its files.

func (*Service) ApplyCodePrune added in v0.9.0 

func (s *Service) ApplyCodePrune(ctx context.Context, repo string, keepLatest int, expectedDelete []string) (*contracts.CorpusPruneResult, error)

ApplyCodePrune deletes the exact confirmed derived code-snapshot plan.

func (*Service) ApplyRepositoryRemoval added in v0.9.0 

func (s *Service) ApplyRepositoryRemoval(ctx context.Context, repo, expectedRevision string) (*contracts.CorpusRepositoryRemovalResult, error)

ApplyRepositoryRemoval applies an unchanged, confirmed repository-removal plan.

func (*Service) ArchiveSync 

func (s *Service) ArchiveSync(ctx context.Context, repo contracts.RepoRef, opts contracts.ArchiveSyncOptions) (*contracts.SyncResult, error)

ArchiveSync adapts CLI archive options to the application sync contract.

func (*Service) ArchiveThreads 

func (s *Service) ArchiveThreads(ctx context.Context, repo contracts.RepoRef, kind, state string, limit int) (*contracts.ThreadListResult, error)

ArchiveThreads returns bounded current thread projections without network access.

func (*Service) AttachValidationReceipt added in v0.14.0 

func (s *Service) AttachValidationReceipt(ctx context.Context, receipt contracts.ExternalValidationReceipt) (*contracts.ValidationRunResult, error)

AttachValidationReceipt imports a structured external receipt without executing its declared command.

func (*Service) BackupCorpus added in v0.9.0 

func (s *Service) BackupCorpus(ctx context.Context, destination string) (*contracts.CorpusBackupResult, error)

BackupCorpus creates a verified online backup at destination.

func (*Service) BuildRepositoryDossier 

func (s *Service) BuildRepositoryDossier(ctx context.Context, repo contracts.RepoRef) (*domain.Dossier, error)

BuildRepositoryDossier builds a deterministic dossier from local corpus data, persists it safely, and returns the result.

func (*Service) CancelJob 

func (s *Service) CancelJob(ctx context.Context, id string) (*contracts.JobResult, error)

CancelJob records and applies a cancellation request, then returns current state.

func (*Service) CheckHypothesisCollisions 

func (s *Service) CheckHypothesisCollisions(ctx context.Context, hypothesisID string, limit int) (*contracts.CollisionCheckResult, error)

CheckHypothesisCollisions searches the local corpus for open pull requests that may collide with a hypothesis.

func (*Service) CheckHypothesisDuplicates 

func (s *Service) CheckHypothesisDuplicates(ctx context.Context, hypothesisID string, limit int) (*contracts.DuplicateCheckResult, error)

CheckHypothesisDuplicates searches the local corpus for threads similar to a hypothesis, returning each finding as evidence.

func (*Service) CheckOpportunityCollisions 

func (s *Service) CheckOpportunityCollisions(ctx context.Context, opportunityID string, limit int) (*contracts.CollisionCheckResult, error)

CheckOpportunityCollisions searches the local corpus for open pull requests that may collide with an opportunity.

func (*Service) CheckOpportunityDuplicates 

func (s *Service) CheckOpportunityDuplicates(ctx context.Context, opportunityID string, limit int) (*contracts.DuplicateCheckResult, error)

CheckOpportunityDuplicates searches the local corpus for threads similar to an opportunity.

func (*Service) Close 

func (s *Service) Close() error

Close cancels and waits for active jobs, then closes the corpus database connection.

func (*Service) Cluster 

func (s *Service) Cluster(ctx context.Context, id string, limit int) (*contracts.ClusterResult, error)

Cluster returns a single cluster by stable id.

func (*Service) CompareValidation 

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

CompareValidation compares a base validation run with a candidate validation run.

func (*Service) Configure 

func (s *Service) Configure(ctx context.Context, opts contracts.ConfigureOptions) (*contracts.ConfigureResult, error)

Configure validates and atomically saves supported typed settings. Runtime environment overrides are deliberately not persisted.

func (*Service) ContributionManifest added in v0.10.0 

func (s *Service) ContributionManifest(ctx context.Context, opportunityID string, opts ManifestOptions) (*manifest.Statement, error)

ContributionManifest assembles and persists one bounded local evidence statement.

func (*Service) ContributionRadar 

func (s *Service) ContributionRadar(ctx context.Context, opts contracts.RadarOptions) (*radar.Report, error)

ContributionRadar ranks a bounded set of locally stored open issues. It is a strict corpus read: it neither resolves a GitHub reader nor writes state.

func (*Service) ControlStatus 

func (s *Service) ControlStatus(ctx context.Context) (*contracts.ControlStatusResult, error)

ControlStatus returns local corpus counts and freshness without network access or implicit hydration.

func (*Service) Coverage 

func (s *Service) Coverage(ctx context.Context, repo contracts.RepoRef) (*contracts.CoverageResult, error)

Coverage returns repository-level facet coverage without network access.

func (*Service) Crawl 

func (s *Service) Crawl(ctx context.Context, name string, opts contracts.CrawlOptions) (*contracts.CrawlResult, error)

Crawl performs one explicit, bounded read for a saved discovery source and persists its checkpoint only after the bounded operation succeeds.

func (*Service) CreateCollection 

func (s *Service) CreateCollection(ctx context.Context, name string) (*contracts.CollectionResult, error)

CreateCollection creates a named collection.

func (*Service) CreateConcern added in v0.10.0 

func (s *Service) CreateConcern(ctx context.Context, opts contracts.ConcernCreateOptions) (*contracts.ConcernResult, error)

CreateConcern records one local concern without external access.

func (*Service) CreateHypothesis 

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

CreateHypothesis records a fully structured hypothesis under an investigation.

func (*Service) CreateWorkspace 

func (s *Service) CreateWorkspace(ctx context.Context, investigationID string, opts contracts.WorkspaceCreateOptions) (*contracts.WorkspaceResult, error)

CreateWorkspace creates a managed worktree for an investigation.

func (*Service) DefineValidation 

func (s *Service) DefineValidation(ctx context.Context, investigationID string, opts contracts.DefineValidationOptions) (*contracts.ValidationResult, error)

DefineValidation stores a validation definition for an investigation.

func (*Service) DiscoverSetup added in v0.3.0 

func (s *Service) DiscoverSetup(ctx context.Context) (*contracts.SetupDiscovery, error)

DiscoverSetup inspects local onboarding state without writes, network access, credential resolution, or process execution.

func (*Service) Doctor 

func (s *Service) Doctor(ctx context.Context) (*contracts.DoctorResult, error)

Doctor performs bounded local diagnostics. It reports authentication source availability but never returns credential values or command output.

func (*Service) Dossier 

func (s *Service) Dossier(ctx context.Context, repo contracts.RepoRef) (*contracts.DossierResult, error)

Dossier builds a deterministic, local-corpus-backed repository dossier.

func (*Service) DuplicateCandidates 

func (s *Service) DuplicateCandidates(ctx context.Context, repo contracts.RepoRef, kind string, number int, limit int) (*DuplicateCandidatesResult, error)

DuplicateCandidates returns the included members of the duplicate-candidate cluster containing the query thread, excluding the query itself. It returns a deterministic order, transparent scores, the cluster stable id, canonical member, and source revision. If the thread is not in a cluster, the result is empty.

func (*Service) ExecuteAction added in v0.14.0 

func (s *Service) ExecuteAction(ctx context.Context, request tuicontract.ActionRequest) (tuicontract.ActionResult, error)

ExecuteAction dispatches a previously offered operation. Every case uses local application services; none performs network access or GitHub mutation.

func (*Service) ExplainLens 

func (s *Service) ExplainLens(ctx context.Context, name, ref string, opts contracts.LensExplainOptions) (*contracts.LensExplainResult, error)

ExplainLens returns the saved definition, candidate facts, normalized signals, weighted contributions, final score, population context, and missing signals for a candidate under a saved lens. It performs no network access.

func (*Service) ExplainMatch 

func (s *Service) ExplainMatch(_ context.Context, query string, match contracts.SearchMatch) (*ExplainMatchResult, error)

ExplainMatch returns factual score reasons for a search match without network access. The returned reasons describe stored text matches, source freshness, and coverage signals.

func (*Service) ExplainReadiness 

func (s *Service) ExplainReadiness(ctx context.Context, checkID string) (*contracts.ReadinessCheck, error)

ExplainReadiness re-evaluates readiness and returns the requested check.

func (*Service) ExportDossier 

func (s *Service) ExportDossier(ctx context.Context, repo contracts.RepoRef, format string) (*contracts.ExportResult, error)

ExportDossier builds and renders a deterministic redacted dossier bundle.

func (*Service) ExportEvidence 

func (s *Service) ExportEvidence(ctx context.Context, investigationID, format string) (*contracts.ExportResult, error)

ExportEvidence renders a deterministic redacted investigation evidence bundle.

func (*Service) ExportLocalMetadata 

func (s *Service) ExportLocalMetadata(ctx context.Context, opts contracts.MetadataExportOptions) (*contracts.MetadataExportResult, error)

ExportLocalMetadata returns a bounded, redacted, deterministic JSON export of local tracking metadata. It does not include tokens, credentials, or absolute local paths.

func (*Service) ExportManifest added in v0.10.0 

func (s *Service) ExportManifest(ctx context.Context, opportunityID string, opts contracts.ManifestExportOptions) (*contracts.ExportResult, error)

ExportManifest generates, persists, and renders one local JSON statement.

func (*Service) ExtractSeeds 

func (s *Service) ExtractSeeds(ctx context.Context, repo contracts.RepoRef, opts domain.ExtractSeedsOptions) ([]domain.Seed, error)

ExtractSeeds derives evidence-backed contribution seeds from locally stored merged PRs, closed-unmerged PRs, and issues. By default it returns only positive and negative outcome evidence; issue-only context is opt-in. It performs no network access.

func (*Service) GetContribution 

func (s *Service) GetContribution(ctx context.Context, id string) (*contracts.ContributionResult, error)

GetContribution returns contribution metadata by durable id.

func (*Service) GetJob 

func (s *Service) GetJob(ctx context.Context, id string) (*contracts.JobResult, error)

GetJob returns one durable job by opaque ID.

func (*Service) GetRepositoryDossier 

func (s *Service) GetRepositoryDossier(ctx context.Context, repo contracts.RepoRef) (*domain.Dossier, error)

GetRepositoryDossier returns the most recently persisted dossier for a repository.

func (*Service) Hydrate 

func (s *Service) Hydrate(ctx context.Context, repo contracts.RepoRef, number int, opts contracts.HydrateOptions) (*contracts.HydrateResult, error)

Hydrate adapts the explicit CLI hydration contract to selective hydration.

func (*Service) HydrateRepository 

func (s *Service) HydrateRepository(ctx context.Context, repo contracts.RepoRef, opts HydrateRepositoryOptions) (*HydrateResult, error)

HydrateRepository hydrates selected facets for threads in a repository. It is explicit, bounded, cancellation-aware, and aggregates per-thread results.

func (*Service) HydrateThread 

func (s *Service) HydrateThread(ctx context.Context, repo contracts.RepoRef, number int, opts HydrateOptions) (*HydrateResult, error)

HydrateThread fetches the requested facets for an issue or pull request and stores immutable facet observations. It is explicit, bounded, paginated, cancellation-aware, and records independent facet coverage plus run completion/failure statistics.

func (*Service) ImportLocalMetadata 

func (s *Service) ImportLocalMetadata(ctx context.Context, opts contracts.MetadataImportOptions) (*contracts.MetadataImportResult, error)

ImportLocalMetadata imports a bounded JSON bundle of local tracking metadata idempotently.

func (*Service) Index 

func (s *Service) Index(ctx context.Context, repo contracts.RepoRef, path string) (*contracts.IndexResult, error)

Index records a bounded immutable code snapshot from a clean local checkout.

func (*Service) Init 

func (s *Service) Init(ctx context.Context) (*contracts.InitResult, error)

Init opens or creates the configured corpus and persists a default configuration if one does not already exist.

func (*Service) InspectCommitChanges added in v0.10.0 

func (s *Service) InspectCommitChanges(ctx context.Context, workspaceID string) (commitplan.Inventory, error)

InspectCommitChanges returns stable assignable units for a managed workspace. It reads only the local worktree and Git object database.

func (*Service) InspectCorpus added in v0.9.0 

func (s *Service) InspectCorpus(ctx context.Context) (*contracts.CorpusInspectionResult, error)

InspectCorpus reports corpus compatibility without mutation.

func (*Service) InventoryCorpus added in v0.9.0 

func (s *Service) InventoryCorpus(ctx context.Context, repo string) (*contracts.CorpusInventoryResult, error)

InventoryCorpus reports bounded storage details for one repository.

func (*Service) Jobs 

func (s *Service) Jobs(ctx context.Context) (*JobExecutor, error)

Jobs returns the durable job executor, opening the corpus if needed.

func (*Service) LinkConcern added in v0.10.0 

func (s *Service) LinkConcern(ctx context.Context, id string, opts contracts.ConcernLinkOptions) (*contracts.ConcernResult, error)

LinkConcern attaches one explicit typed relationship.

func (*Service) ListClusters added in v0.8.0 

func (s *Service) ListClusters(ctx context.Context, repo contracts.RepoRef, limit int) (*contracts.ClusterListResult, error)

ListClusters reads the current stored duplicate-candidate projection. It does not compute or write cluster state.

func (*Service) ListCollections 

func (s *Service) ListCollections(ctx context.Context) (*contracts.CollectionListResult, error)

ListCollections returns all named collections.

func (*Service) ListConcerns added in v0.10.0 

func (s *Service) ListConcerns(ctx context.Context, opts contracts.ConcernListOptions) (*contracts.ConcernListResult, error)

ListConcerns performs a bounded offline concern list or search.

func (*Service) ListContributionOutcomes 

func (s *Service) ListContributionOutcomes(ctx context.Context, contributionID string) (*contracts.ContributionOutcomeListResult, error)

ListContributionOutcomes returns lifecycle outcomes for a contribution.

func (*Service) ListContributions 

func (s *Service) ListContributions(ctx context.Context, opts contracts.ListContributionsOptions) (*contracts.ContributionListResult, error)

ListContributions returns contribution metadata in prepared-at order.

func (*Service) ListCorpusInventory added in v0.9.0 

func (s *Service) ListCorpusInventory(ctx context.Context) (*contracts.CorpusInventoryListResult, error)

ListCorpusInventory reports bounded storage details for every repository scope.

func (*Service) ListCorpusProjections added in v0.9.0 

func (s *Service) ListCorpusProjections(ctx context.Context) (*contracts.CorpusProjectionListResult, error)

ListCorpusProjections reports derived projection identities and freshness.

func (*Service) ListHypotheses 

func (s *Service) ListHypotheses(ctx context.Context, investigationID string) (*contracts.HypothesisListResult, error)

ListHypotheses returns hypotheses for an investigation.

func (*Service) ListInvestigations 

func (s *Service) ListInvestigations(ctx context.Context) (*contracts.InvestigationListResult, error)

ListInvestigations returns all investigations.

func (*Service) ListJobs 

func (s *Service) ListJobs(ctx context.Context, status string, limit int) (*contracts.JobListResult, error)

ListJobs returns bounded durable jobs for CLI and MCP adapters.

func (*Service) ListLenses 

func (s *Service) ListLenses(ctx context.Context) (*contracts.LensListResult, error)

ListLenses returns all saved lenses in stable order.

func (*Service) ListOpportunities 

func (s *Service) ListOpportunities(ctx context.Context, investigationID string) (*contracts.OpportunityListResult, error)

ListOpportunities returns opportunities, optionally filtered to one investigation.

func (*Service) ListSources 

func (s *Service) ListSources(ctx context.Context) (*contracts.SourceListResult, error)

ListSources returns all saved discovery sources from the local corpus.

func (*Service) ListTriageEvents 

func (s *Service) ListTriageEvents(ctx context.Context, opts contracts.ListTriageEventsOptions) (*contracts.TriageEventListResult, error)

ListTriageEvents returns local triage outcomes in source-event order.

func (*Service) Load 

func (s *Service) Load(ctx context.Context) (tuicontract.Data, error)

Load implements tuicontract.Reader using bounded local corpus reads only.

func (*Service) MCPReader 

func (s *Service) MCPReader() mcpcontract.Reader

MCPReader returns an MCP adapter backed by this service. Read methods remain offline; methods named sync or hydrate are explicit network-read operations.

func (*Service) Metadata 

func (s *Service) Metadata(ctx context.Context) (*contracts.MetadataResult, error)

Metadata reports deterministic application and local capability metadata. It performs no network access and never creates or migrates the corpus.

func (*Service) MigrateCorpus added in v0.9.0 

func (s *Service) MigrateCorpus(ctx context.Context, opts contracts.CorpusMigrateOptions) (*contracts.CorpusMigrationResult, error)

MigrateCorpus explicitly applies pending schema migrations with backup policy.

func (*Service) NeighborQuery 

func (s *Service) NeighborQuery(ctx context.Context, repo contracts.RepoRef, kind string, number, limit int) (*contracts.NeighborListResult, error)

NeighborQuery returns transparent local nearest-thread results.

func (*Service) Neighbors 

func (s *Service) Neighbors(ctx context.Context, repo contracts.RepoRef, kind string, number int, limit int) (*NeighborsResult, error)

Neighbors returns a bounded, ranked list of threads most similar to the query thread. Results include transparent scores, reasons, and the source revision of the candidate population. No network access occurs.

func (*Service) OpportunityReadiness 

func (s *Service) OpportunityReadiness(ctx context.Context, opportunityID string) (*contracts.ReadinessResult, error)

OpportunityReadiness evaluates local, source-backed readiness checks for one opportunity.

func (*Service) PlanArchiveSync added in v0.8.0 

func (s *Service) PlanArchiveSync(_ context.Context, repo contracts.RepoRef, opts contracts.ArchiveSyncOptions) (*contracts.SyncPlanResult, error)

PlanArchiveSync computes the conservative request ceiling before resolving a GitHub reader or opening the corpus.

func (*Service) PlanCodePrune added in v0.9.0 

func (s *Service) PlanCodePrune(ctx context.Context, repo string, keepLatest int) (*contracts.CorpusPruneResult, error)

PlanCodePrune previews derived code snapshots eligible for deletion.

func (*Service) PlanRepositoryContextSync added in v0.13.0 

func (s *Service) PlanRepositoryContextSync(_ context.Context, repo contracts.RepoRef, maxRequests int) (*contracts.SyncPlanResult, error)

func (*Service) PlanRepositoryRemoval added in v0.9.0 

func (s *Service) PlanRepositoryRemoval(ctx context.Context, repo string) (*contracts.CorpusRepositoryRemovalResult, error)

PlanRepositoryRemoval previews the exact repository-owned removal scope.

func (*Service) PlanSemanticCommits added in v0.10.0 

func (s *Service) PlanSemanticCommits(ctx context.Context, workspaceID, expectedInventorySHA256 string, input commitplan.PlanInput) (commitplan.Plan, error)

PlanSemanticCommits validates agent-authored semantic groups against the current workspace snapshot. It never stages changes or rewrites history.

func (*Service) PrepareIssue 

func (s *Service) PrepareIssue(ctx context.Context, opportunityID string, opts contracts.PrepareIssueOptions) (*contracts.DraftResult, error)

PrepareIssue renders and stores an issue draft for an opportunity.

func (*Service) PreparePullRequest 

func (s *Service) PreparePullRequest(ctx context.Context, opportunityID string, opts contracts.PreparePROptions) (*contracts.DraftResult, error)

PreparePullRequest renders and stores a pull request draft for an opportunity.

func (*Service) PrepareReviewReport 

func (s *Service) PrepareReviewReport(ctx context.Context, input contracts.PrepareReviewReportInput) (*contracts.ReviewReport, error)

PrepareReviewReport assembles a review report for an opportunity and/or workspace.

func (*Service) PromoteConcern added in v0.10.0 

func (s *Service) PromoteConcern(ctx context.Context, id string, opts contracts.ConcernPromoteOptions) (*contracts.ConcernResult, error)

PromoteConcern atomically creates downstream investigation workflow records.

func (*Service) PromoteOpportunity 

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

PromoteOpportunity converts a proposed hypothesis into an opportunity.

func (*Service) PromoteOpportunityWithInput 

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

PromoteOpportunityWithInput promotes a hypothesis with dependencies and maintainer-alignment evidence.

func (*Service) PullRequestCollisions 

func (s *Service) PullRequestCollisions(ctx context.Context, repo contracts.RepoRef, number int, limit int) (*PullRequestCollisionResult, error)

PullRequestCollisions returns a bounded, ranked list of open pull requests that may collide with the query PR. It uses only existing local data: base branch from the stored PR payload, explicit cross-references in the title/body, and shared author. No network access occurs and no semantic file overlap is invented.

func (*Service) RebuildCorpusProjection added in v0.9.0 

func (s *Service) RebuildCorpusProjection(ctx context.Context, name string) (*contracts.CorpusProjectionResult, error)

RebuildCorpusProjection explicitly replaces one derived search projection.

func (*Service) RecordContribution 

func (s *Service) RecordContribution(ctx context.Context, opts contracts.RecordContributionOptions) (*contracts.ContributionResult, error)

RecordContribution stores prepared or submitted contribution metadata for an opportunity, keeping it separate from live GitHub state.

func (*Service) RecordContributionOutcome 

func (s *Service) RecordContributionOutcome(ctx context.Context, opts contracts.RecordContributionOutcomeOptions) (*contracts.ContributionOutcomeResult, error)

RecordContributionOutcome stores a lifecycle outcome for a contribution.

func (*Service) RecordEvidence 

func (s *Service) RecordEvidence(ctx context.Context, input contracts.RecordEvidenceInput) (*evidence.Evidence, error)

RecordEvidence stores an evidence item scoped to its parent workflow.

func (*Service) RecordTriageEvent 

func (s *Service) RecordTriageEvent(ctx context.Context, opts contracts.RecordTriageEventOptions) (*contracts.TriageEventResult, error)

RecordTriageEvent records a local triage or feedback outcome for a typed target.

func (*Service) RefreshClusters added in v0.8.0 

func (s *Service) RefreshClusters(ctx context.Context, repo contracts.RepoRef) (*contracts.ClusterRefreshResult, error)

RefreshClusters explicitly computes and persists the duplicate-candidate projection for a repository.

func (*Service) RepositoryContextSync added in v0.13.0 

func (s *Service) RepositoryContextSync(ctx context.Context, repo contracts.RepoRef, maxRequests int) (_ *contracts.RepositoryContextResult, resultErr error)

func (*Service) RepositoryHealth 

func (s *Service) RepositoryHealth(ctx context.Context, repo contracts.RepoRef) (*health.Report, error)

RepositoryHealth returns a deterministic repository health report derived from already stored corpus facts. It performs no network access.

func (*Service) RepositoryHealthWithOptions 

func (s *Service) RepositoryHealthWithOptions(ctx context.Context, repo contracts.RepoRef, opts health.Options) (*health.Report, error)

RepositoryHealthWithOptions returns a deterministic repository health report using the provided analysis window and stale threshold.

func (*Service) ResearchBrief added in v0.14.0 

func (s *Service) ResearchBrief(ctx context.Context, item tuicontract.Item) (tuicontract.ResearchBrief, error)

ResearchBrief projects the existing source-backed local research package into the terminal contract. It performs no network access or mutation.

func (*Service) RestoreCorpus added in v0.9.0 

func (s *Service) RestoreCorpus(ctx context.Context, source, safetyBackup string) (*contracts.CorpusRestoreResult, error)

RestoreCorpus replaces the corpus from a verified backup after safety backup.

func (*Service) RunHistory 

func (s *Service) RunHistory(ctx context.Context, limit int) (*contracts.RunListResult, error)

RunHistory returns bounded durable run metadata.

func (*Service) RunValidation 

func (s *Service) RunValidation(ctx context.Context, id string, opts contracts.RunValidationOptions) (*contracts.ValidationRunResult, error)

RunValidation executes a stored validation definition against the base or candidate workspace.

func (*Service) RunValidationGroup added in v0.10.0 

func (s *Service) RunValidationGroup(ctx context.Context, id string, opts contracts.RepeatValidationOptions) (*contracts.ValidationRunGroupResult, error)

RunValidationGroup executes a bounded repeat/stress validation group.

func (*Service) RuntimeContract added in v0.9.0 

func (s *Service) RuntimeContract(ctx context.Context) (*contracts.RuntimeContractResult, error)

RuntimeContract reports immutable executable compatibility metadata.

func (*Service) Search 

func (s *Service) Search(ctx context.Context, query string, opts contracts.SearchOptions) (*contracts.SearchResult, error)

Search performs a local-only corpus search and supports repo and kind filters.

func (*Service) SetArchiveFetcher 

func (s *Service) SetArchiveFetcher(f discovery.ArchiveFetcher)

SetArchiveFetcher overrides the GH Archive fetcher. It is intended for tests.

func (*Service) SetClock 

func (s *Service) SetClock(clock func() time.Time)

SetClock overrides the time source. It is intended for tests.

func (*Service) SetConcernStatus added in v0.10.0 

func (s *Service) SetConcernStatus(ctx context.Context, id, status, rationale string) (*contracts.ConcernResult, error)

SetConcernStatus applies one validated non-promotion transition.

func (*Service) SetDeepWikiReader added in v0.5.0 

func (s *Service) SetDeepWikiReader(r deepwiki.Reader)

SetDeepWikiReader overrides the derived external knowledge reader. It is intended for tests and embedding.

func (*Service) SetGitHubReader 

func (s *Service) SetGitHubReader(r github.Reader)

SetGitHubReader overrides the GitHub reader. It is intended for tests.

func (*Service) SetOpportunityStatus 

func (s *Service) SetOpportunityStatus(ctx context.Context, id, status, rationale string) (*contracts.OpportunityResult, error)

SetOpportunityStatus transitions an opportunity with a recorded rationale.

func (*Service) Setup 

func (s *Service) Setup(ctx context.Context, opts contracts.SetupOptions) (*contracts.SetupReport, error)

Setup initializes local state for one of three access modes. MCP-only setup copies the running native executable into a private product-owned directory; CLI-only setup installs the published command globally through npm; Both registers that verified global executable with selected coding clients. Installation failures stop before later configuration writes.

Dry-run setup validates and reports the same access-mode plan without invoking npm or writing local state. Setup performs no GitHub access and never executes repository-controlled code.

func (*Service) SetupWithProgress added in v0.3.0 

func (s *Service) SetupWithProgress(ctx context.Context, opts contracts.SetupOptions, observer contracts.SetupObserver) (*contracts.SetupReport, error)

SetupWithProgress applies setup while reporting phase changes to an optional observer owned by the interactive CLI adapter.

func (*Service) ShowConcern added in v0.10.0 

func (s *Service) ShowConcern(ctx context.Context, id string) (*contracts.ConcernResult, error)

ShowConcern returns one local concern with derived freshness.

func (*Service) ShowEvidence 

func (s *Service) ShowEvidence(ctx context.Context, investigationID string) (*contracts.EvidenceResult, error)

ShowEvidence returns the evidence packet for an investigation.

func (*Service) ShowInvestigation 

func (s *Service) ShowInvestigation(ctx context.Context, id string) (*contracts.InvestigationResult, error)

ShowInvestigation returns an investigation by ID.

func (*Service) ShowLens 

func (s *Service) ShowLens(ctx context.Context, name string) (*contracts.LensResult, error)

ShowLens returns a saved lens by name.

func (*Service) ShowOpportunity 

func (s *Service) ShowOpportunity(ctx context.Context, id string) (*contracts.OpportunityResult, error)

ShowOpportunity returns an opportunity by ID.

func (*Service) ShowSource 

func (s *Service) ShowSource(ctx context.Context, name string) (*contracts.SourceResult, error)

ShowSource returns one saved discovery source from the local corpus.

func (*Service) ShowValidation 

func (s *Service) ShowValidation(ctx context.Context, id string) (*contracts.ValidationResult, error)

ShowValidation returns a stored validation definition without executing it.

func (*Service) ShowWorkspace 

func (s *Service) ShowWorkspace(ctx context.Context, id string) (*contracts.WorkspaceResult, error)

ShowWorkspace returns a workspace by ID with its current dirty state.

func (*Service) StartInvestigation 

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

StartInvestigation creates a new investigation scoped to a repository.

func (*Service) StartInvestigationFromThread 

func (s *Service) StartInvestigationFromThread(ctx context.Context, requested research.ThreadRef) (*contracts.ThreadInvestigationResult, error)

StartInvestigationFromThread atomically creates an investigation and seed hypothesis from one exact local observation. It performs no network access or process execution.

func (*Service) Status 

func (s *Service) Status(ctx context.Context) (*contracts.StatusResult, error)

Status reports whether the corpus is healthy and counts local records.

func (*Service) TailSource 

func (s *Service) TailSource(ctx context.Context, name string, opts contracts.TailOptions) (*contracts.TailResult, error)

TailSource repeatedly advances a named source until cancellation. Each iteration is an ordinary idempotent crawl and therefore retains its own run record, checkpoint, request budget, and failure state.

func (*Service) ThreadResearchBrief 

func (s *Service) ThreadResearchBrief(ctx context.Context, ref research.ThreadRef) (*research.Brief, error)

ThreadResearchBrief builds a deterministic brief from the local corpus. It performs no network access, local mutation, or process execution.

func (*Service) TransitionHypothesis 

func (s *Service) TransitionHypothesis(ctx context.Context, hypothesisID, status, rationale string) (*investigation.Hypothesis, error)

TransitionHypothesis advances a hypothesis through its lifecycle with rationale.

func (*Service) UpdateConcern added in v0.10.0 

func (s *Service) UpdateConcern(ctx context.Context, id string, opts contracts.ConcernUpdateOptions) (*contracts.ConcernResult, error)

UpdateConcern changes editable concern content without changing status.

func (*Service) UpdateHypothesis 

func (s *Service) UpdateHypothesis(ctx context.Context, hypothesisID string, input investigation.UpdateHypothesisInput) (*investigation.Hypothesis, error)

UpdateHypothesis deliberately overwrites a hypothesis with rationale.

func (*Service) UpdateHypothesisFields added in v0.11.0 

func (s *Service) UpdateHypothesisFields(ctx context.Context, hypothesisID string, opts contracts.HypothesisUpdateOptions) (*investigation.Hypothesis, error)

UpdateHypothesisFields applies a partial update without making callers reconstruct unchanged hypothesis state.

func (*Service) UpdateOpportunityCollisionStatus 

func (s *Service) UpdateOpportunityCollisionStatus(ctx context.Context, opportunityID, status, rationale string) (*investigation.Opportunity, error)

UpdateOpportunityCollisionStatus explicitly sets the collision status with rationale.

func (*Service) Upgrade 

func (s *Service) Upgrade(ctx context.Context, opts contracts.UpgradeOptions) (*contracts.UpgradeReport, error)

Upgrade checks npm for the latest release and updates persistent npm installations when explicitly authorized. It reports inspectable stages covering the npm launcher, private MCP runtime, configured client runtime, corpus schema compatibility, activation/restart action, and rollback limitations. It does not migrate the corpus or silently update an npx invocation.

func (*Service) VerifyPublishedDraft added in v0.14.0 

func (s *Service) VerifyPublishedDraft(ctx context.Context, in contracts.VerifyPublishedDraftInput) (*contracts.PublishedDraftVerification, error)

VerifyPublishedDraft compares one immutable local revision with one explicitly synchronized GitHub thread and never performs a network read.

func (*Service) WorkspaceDiff 

func (s *Service) WorkspaceDiff(ctx context.Context, id string) (*contracts.WorkspaceDiffResult, error)

WorkspaceDiff returns the current diff of a workspace against its recorded base, including changed files and a suggested review order.

type SyncOptions 

type SyncOptions struct {
	Kind        string
	State       string
	Since       time.Time
	Numbers     []int
	MaxItems    int
	MaxPages    int
	MaxRequests int
}

SyncOptions bounds and filters an explicit repository synchronization.

type ThreadRef 

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

ThreadRef identifies a thread with minimal fields.

Source Files

View all Source files

Jump to

Keyboard shortcuts

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