corpus

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Jul 21, 2026 License: MIT Imports: 42 Imported by: 0

Documentation

Overview

Package corpus provides the product-owned SQLite system of record.

The corpus stores immutable source observations separately from normalized current-state projections. Projection writes reject stale source revisions, complete paginated facets replace prior children atomically, and local queries use deterministic ordering. Opening a corpus applies embedded Goose migrations and performs no network or process work.

Index

Constants

View Source 
const (
	FrontierQueued    = "queued"
	FrontierLeased    = "leased"
	FrontierCompleted = "completed"
	FrontierFailed    = "failed"
)

FrontierState describes the durable lifecycle of queued crawl work.

View Source 
const (
	FrontierFailureTransientExhausted = "transient_exhausted"
	FrontierFailureAbsent             = "absent"
	FrontierFailureUnauthorized       = "unauthorized"
	FrontierFailureDeleted            = "deleted"
	FrontierFailureArchived           = "archived"
	FrontierFailurePermanent          = "permanent"
)

Frontier failure classifications keep terminal source outcomes distinct.

View Source 
const (
	ThreadKindIssue       = "issue"
	ThreadKindPullRequest = "pull_request"
)

ThreadKind names the thread types stored by the corpus.

View Source 
const (
	RunStatusRunning   = "running"
	RunStatusCompleted = "completed"
	RunStatusPartial   = "partial"
	RunStatusFailed    = "failed"
)

RunStatus values.

View Source 
const (
	JobStatusQueued    = "queued"
	JobStatusRunning   = "running"
	JobStatusSucceeded = "succeeded"
	JobStatusFailed    = "failed"
	JobStatusCancelled = "cancelled"
)

JobStatus values for the durable job lifecycle.

View Source 
const (
	// PortfolioSubjectPullRequest identifies a corpus pull-request thread.
	PortfolioSubjectPullRequest = "pull_request"
	// PortfolioSubjectOpportunity identifies a local contribution opportunity.
	PortfolioSubjectOpportunity = "opportunity"
	// PortfolioSubjectWorkspace identifies a local contribution workspace.
	PortfolioSubjectWorkspace = "workspace"

	// PortfolioFacetChangedFiles contains normalized changed paths.
	PortfolioFacetChangedFiles = "changed_files"
	// PortfolioFacetLinkedIssues contains normalized issue references.
	PortfolioFacetLinkedIssues = "linked_issues"
	// PortfolioFacetOpportunitySimilarity contains scored PR relationships.
	PortfolioFacetOpportunitySimilarity = "opportunity_similarity"

	// PortfolioSignalFilePath is a normalized changed-path signal.
	PortfolioSignalFilePath = "file_path"
	// PortfolioSignalLinkedIssue is a normalized linked-issue signal.
	PortfolioSignalLinkedIssue = "linked_issue"
	// PortfolioSignalOpportunitySimilarity is a scored subject relationship.
	PortfolioSignalOpportunitySimilarity = "opportunity_similarity"
)
View Source 
const (
	ProjectionNameThreadsFTS           = "threads_fts"
	ProjectionNameFacetObservationsFTS = "facet_observations_fts"
	ProjectionNameCodeDocumentsFTS     = "code_documents_fts"
)

Product-owned names for derived SQLite search projections.

View Source 
const (
	ProjectionVersionThreadsFTS           = "threads-fts-v1"
	ProjectionVersionFacetObservationsFTS = "facet-observations-fts-v1"
	ProjectionVersionCodeDocumentsFTS     = "code-documents-fts-v1"
)

Product-owned versions for derived SQLite search projections.

Variables

View Source 
var (
	ErrProjectionNotFound = errors.New("projection state not found")
	ErrProjectionStale    = errors.New("search projection is stale or missing")
)

Projection errors.

View Source 
var ErrCodeSnapshotPrunePlanStale = errors.New("code snapshot prune plan is stale")

ErrCodeSnapshotPrunePlanStale indicates that a confirmed prune preview changed.

View Source 
var ErrJobCancelled = errors.New("job cancellation requested")

ErrJobCancelled is returned when a terminal transition is blocked because a cancellation has already been requested for the job.

View Source 
var ErrJobOwnerNotFound = errors.New("job owner not found")

ErrJobOwnerNotFound is returned when a heartbeat targets an owner row that no longer exists.

View Source 
var ErrRepositoryNotFound = errors.New("repository not found in corpus")

ErrRepositoryNotFound indicates that an inventory scope is absent.

View Source 
var ErrRepositoryRemovalPlanStale = errors.New("repository removal plan is stale")

ErrRepositoryRemovalPlanStale indicates that a confirmed removal preview changed.

View Source 
var ErrResolutionNotFound = errors.New("resolution record not found")

ErrResolutionNotFound indicates that no current resolution projection exists.

View Source 
var ErrThreadObservationRevisionNotFound = errors.New("thread observation revision not found")

ErrThreadObservationRevisionNotFound reports a projection revision whose immutable source observation is unavailable.

Functions

func CheckExclusiveAccess added in v0.9.0 

func CheckExclusiveAccess(path, operation string) error

CheckExclusiveAccess fails fast when another cooperating process holds a corpus lease. It makes no database changes and does not reserve the lease for later work; the mutating operation must acquire it again.

func CheckWriteAccessAtPath added in v0.9.0 

func CheckWriteAccessAtPath(ctx context.Context, path string) (returnErr error)

CheckWriteAccessAtPath checks whether an existing compatible corpus can begin a write transaction without opening the migration-capable corpus path. The transaction is always rolled back and no schema or archive data changes.

func InspectSchemaVersion added in v0.8.0 

func InspectSchemaVersion(ctx context.Context, path string) (int64, bool, error)

InspectSchemaVersion reads the applied schema version from an existing corpus without creating the database or applying migrations. The boolean is false when path has no persistent database to inspect.

func Migrate added in v0.9.0 

func Migrate(ctx context.Context, path string, observer MigrationObserver) (returnErr error)

Migrate opens or creates a persistent corpus, applies pending migrations with explicit progress, verifies connection pragmas, and closes it. Callers own consent, backup policy, and activation of any dependent runtime.

func RestoreWithSafetyBackup added in v0.9.0 

func RestoreWithSafetyBackup(ctx context.Context, source, destination, safetyDestination string, observer func(copied, total int)) (_ *BackupResult, _ BackupResult, returnErr error)

RestoreWithSafetyBackup holds one exclusive destination lease while taking the safety backup, replacing the corpus, and verifying the restored state. The returned safety backup remains available when restore fails.

func SupportedSchemaVersion added in v0.9.0 

func SupportedSchemaVersion() (int64, error)

SupportedSchemaVersion returns the newest embedded corpus schema without opening a database or inspecting the filesystem.

Types

type BackupManifest added in v0.9.0 

type BackupManifest struct {
	FormatVersion  int         `json:"format_version"`
	CreatedAt      time.Time   `json:"created_at"`
	SizeBytes      int64       `json:"size_bytes"`
	SHA256         string      `json:"sha256"`
	SourceSchema   int64       `json:"source_schema"`
	ExpectedSchema int64       `json:"expected_schema"`
	Compatibility  SchemaState `json:"compatibility"`
}

BackupManifest is stored next to each backup so restore can reject partial, corrupted, or incompatible artifacts before touching the live corpus.

type BackupResult added in v0.9.0 

type BackupResult struct {
	Path           string
	ManifestPath   string
	SizeBytes      int64
	SHA256         string
	CreatedAt      time.Time
	SourceSchema   int64
	ExpectedSchema int64
	Compatibility  SchemaState
}

BackupResult identifies a verified, consistent SQLite backup.

func Backup added in v0.9.0 

func Backup(ctx context.Context, source, destination string, observer func(copied, total int)) (_ BackupResult, returnErr error)

Backup creates and verifies an online SQLite backup, including committed WAL content visible to the source connection, before atomically publishing it.

func MigrateWithBackup added in v0.9.0 

func MigrateWithBackup(ctx context.Context, path, backupDestination string, observer MigrationObserver) (_ *BackupResult, returnErr error)

MigrateWithBackup holds one exclusive corpus lease from the start of the safety backup through migration verification. An empty backup destination explicitly opts out of backup creation.

func Restore added in v0.9.0 

func Restore(ctx context.Context, source, destination string, observer func(copied, total int)) (_ BackupResult, returnErr error)

Restore atomically replaces a corpus from a verified backup.

type BusyError added in v0.9.0 

type BusyError struct {
	Path      string
	Operation string
}

BusyError reports that another GitContribute process holds an incompatible corpus lease. Operations fail fast instead of appearing hung.

func (*BusyError) Error added in v0.9.0 

func (e *BusyError) Error() string

type CodeMatch 

type CodeMatch struct {
	Repo              domain.RepoRef
	Commit            string
	Path              string
	Content           string
	Bytes             int
	Language          string
	SnapshotID        int64
	DocID             int64
	SnapshotCreatedAt time.Time
	Rank              float64
}

CodeMatch is one local code-search result at an immutable commit.

type CodeSearchOptions 

type CodeSearchOptions struct {
	Ref    domain.RepoRef
	Limit  int
	Cursor string
}

CodeSearchOptions scopes a paginated code-document keyword search.

type CodeSearchPage 

type CodeSearchPage struct {
	Matches    []CodeMatch
	NextCursor string
	Total      int
}

CodeSearchPage is a paginated result of a code-document keyword search.

type CodeSnapshotPrunePlan added in v0.9.0 

type CodeSnapshotPrunePlan struct {
	Ref            domain.RepoRef
	KeepLatest     int
	TotalSnapshots int
	Keep           []CodeSnapshotRef
	Delete         []CodeSnapshotRef
	ReclaimBytes   int64
}

CodeSnapshotPrunePlan is a dry-run plan for pruning derived code snapshots. It never describes durable GitHub observations.

type CodeSnapshotPruneResult added in v0.9.0 

type CodeSnapshotPruneResult struct {
	Ref          domain.RepoRef
	KeepLatest   int
	Deleted      int
	ReclaimBytes int64
}

CodeSnapshotPruneResult reports how many derived code snapshots were removed.

type CodeSnapshotRef added in v0.9.0 

type CodeSnapshotRef struct {
	ID         int64
	CommitSHA  string
	CreatedAt  time.Time
	TotalBytes int64
}

CodeSnapshotRef identifies one stored code snapshot for retention planning.

type Collection 

type Collection struct {
	ID          int64
	Name        string
	MemberCount int
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Collection is a named set of local corpus references.

type CollectionMember 

type CollectionMember struct {
	Ref     string
	Kind    string
	AddedAt time.Time
}

CollectionMember is one typed stable reference in a collection.

type ControlStats 

type ControlStats struct {
	Repositories  int
	Threads       int
	Sources       int
	FrontierReady int
	ActiveRuns    int
	ActiveJobs    int
	Freshest      time.Time
}

ControlStats is a bounded local snapshot used by status and diagnostics.

type Corpus 

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

Corpus is a durable, product-owned SQLite archive for GitHub repositories and threads. It stores immutable observations and separately maintained current projections, runs, coverage facts, and FTS5 search indexes.

func Open 

func Open(ctx context.Context, path string) (_ *Corpus, returnErr error)

Open opens or creates a corpus at path, applies pending migrations, and enables WAL, foreign keys, and a busy timeout. The returned Corpus is safe for concurrent use by a single writer with multiple readers.

func OpenReadOnly added in v0.9.0 

func OpenReadOnly(ctx context.Context, path string) (_ *Corpus, returnErr error)

OpenReadOnly opens an existing, current corpus without creating files or applying migrations. It returns a typed compatibility error when migration or a newer binary is required.

func (*Corpus) AddClusterOverride added in v0.8.0 

func (c *Corpus) AddClusterOverride(ctx context.Context, clusterID int64, ref clustering.MemberRef, action clustering.OverrideAction, reason string) (err error)

AddClusterOverride validates and records one explicit membership decision, then advances the repository governance revision in the same transaction. It does not recompute clusters; the next explicit refresh applies the decision. The canonical member cannot be excluded.

func (*Corpus) AddCollectionMembers 

func (c *Corpus) AddCollectionMembers(ctx context.Context, collectionName string, members []CollectionMember) error

AddCollectionMembers idempotently adds a bounded batch of typed references.

func (*Corpus) AdvanceFacet 

func (c *Corpus) AdvanceFacet(ctx context.Context, repoID int64, threadID *int64, facet string, sourceUpdatedAt time.Time, complete bool, runID int64) error

AdvanceFacet records progress on a hydration facet for a repository or thread. The update wins only when the new (source_updated_at, observation_sequence) ordering is greater, so facets advance independently from one another and from the parent projection.

func (*Corpus) AdvanceFacetCAS added in v0.6.0 

func (c *Corpus) AdvanceFacetCAS(ctx context.Context, repoID int64, threadID *int64, facet string, sourceUpdatedAt time.Time, complete bool, runID, expectedSequence int64) (bool, error)

AdvanceFacetCAS advances coverage only when the facet sequence captured before retrieval is still current.

func (*Corpus) ApplyCodeSnapshotPrune added in v0.9.0 

func (c *Corpus) ApplyCodeSnapshotPrune(ctx context.Context, ref domain.RepoRef, plan *CodeSnapshotPrunePlan) (_ *CodeSnapshotPruneResult, err error)

ApplyCodeSnapshotPrune transactionally prunes derived code snapshots so that only the latest N remain for the repository. It requires the plan's scope to match the supplied repository reference and recomputes the delete set inside the transaction to preserve the latest N against concurrent inserts.

func (*Corpus) ApplyFacetObservationSet 

func (c *Corpus) ApplyFacetObservationSet(ctx context.Context, repoID int64, threadID *int64, facet string, sourceUpdatedAt time.Time, pages []FacetObservationInput, complete bool, runID int64) error

ApplyFacetObservationSet records a complete ordered set of facet observations and advances coverage for the facet in a single transaction. The existing facet observations are replaced only when the new set wins the (source_updated_at, observation_sequence) ordering, so an interrupted or stale fetch leaves previous complete data in place.

sourceUpdatedAt is the authoritative source timestamp for the set as a whole. It is used when the set is empty and also combined with the per-page timestamps so the latest source timestamp always controls the ordering. Callers should pass the most recent source timestamp available for the facet (for example, the latest item update time, falling back to the thread's source_updated_at).

func (*Corpus) ApplyFacetObservationSetCAS added in v0.6.0 

func (c *Corpus) ApplyFacetObservationSetCAS(ctx context.Context, repoID int64, threadID *int64, facet string, sourceUpdatedAt time.Time, pages []FacetObservationInput, complete bool, runID, expectedSequence int64) (bool, error)

ApplyFacetObservationSetCAS atomically replaces a facet only when its current coverage sequence still matches the sequence captured before retrieval.

func (*Corpus) ApplyFacetObservationSetIfNewer added in v0.8.0 

func (c *Corpus) ApplyFacetObservationSetIfNewer(ctx context.Context, repoID int64, threadID *int64, facet string, sourceUpdatedAt time.Time, pages []FacetObservationInput, complete bool, runID int64) (applied bool, err error)

ApplyFacetObservationSetIfNewer records a facet snapshot and reports whether it won the stored source ordering. Callers that maintain a derived projection must update it only when applied is true.

func (*Corpus) ApplyMigrations added in v0.9.0 

func (c *Corpus) ApplyMigrations(ctx context.Context, observer MigrationObserver) error

ApplyMigrations applies pending migrations one at a time and reports stable step boundaries. The caller owns authorization, backup, and process leases.

func (*Corpus) ApplyRepositoryObservation 

func (c *Corpus) ApplyRepositoryObservation(ctx context.Context, owner, name, externalID string, sourceUpdatedAt time.Time, payload string) (*Repository, error)

ApplyRepositoryObservation records an immutable repository observation and updates the current projection only when the new observation wins the ordering (source_updated_at, then observation_sequence).

func (*Corpus) ApplyRepositoryRemoval added in v0.9.0 

func (c *Corpus) ApplyRepositoryRemoval(ctx context.Context, ref domain.RepoRef, plan *RepositoryRemovalPlan) (_ *RepositoryRemovalResult, err error)

ApplyRepositoryRemoval verifies the preview inside a transaction and then removes only the named repository's observations and replaceable projections.

func (*Corpus) ApplyThreadObservation 

func (c *Corpus) ApplyThreadObservation(ctx context.Context, repoID int64, kind string, number int, state, title, body, author string, sourceUpdatedAt time.Time, payload string) (*Thread, error)

ApplyThreadObservation records an immutable thread observation and updates the current projection only when the new observation wins the ordering.

func (*Corpus) CheckIntegrity 

func (c *Corpus) CheckIntegrity(ctx context.Context) error

CheckIntegrity performs a bounded, local database integrity check.

func (*Corpus) CheckWriteAccess added in v0.7.1 

func (c *Corpus) CheckWriteAccess(ctx context.Context) (err error)

CheckWriteAccess reports whether a write transaction can begin immediately. Contention is an availability signal, not evidence of database corruption.

func (*Corpus) Close 

func (c *Corpus) Close() error

Close closes the underlying database connection.

func (*Corpus) CommitClusterProjection added in v0.8.0 

func (c *Corpus) CommitClusterProjection(ctx context.Context, commit clusterprojection.Commit) (result clusterprojection.CommitResult, err error)

CommitClusterProjection validates a complete refresh result, obtains the SQLite writer, rechecks source and governance revisions, and atomically advances the current projection. Exact computation must already be complete; this method never performs pair evaluation while holding the transaction.

func (*Corpus) CompleteFrontierItem 

func (c *Corpus) CompleteFrontierItem(ctx context.Context, id int64, worker string, now time.Time) error

CompleteFrontierItem marks leased work complete. Only the lease owner can complete it, preventing a stale worker from overwriting a newer attempt.

func (*Corpus) ControlStats 

func (c *Corpus) ControlStats(ctx context.Context, now time.Time) (ControlStats, error)

ControlStats returns local counts without triggering refresh or hydration.

func (*Corpus) CountThreadsFiltered 

func (c *Corpus) CountThreadsFiltered(ctx context.Context, repoID int64, kind, state string) (int, error)

CountThreadsFiltered counts threads after applying the same kind and state predicates as ListThreadsFiltered.

func (*Corpus) CreateEvidence 

func (c *Corpus) CreateEvidence(ctx context.Context, item *evidence.Evidence) error

CreateEvidence inserts evidence through the repository boundary.

func (*Corpus) CreateJob 

func (c *Corpus) CreateJob(ctx context.Context, kind, request string) (*Job, error)

CreateJob creates a new job in the queued state with an opaque stable ID.

func (*Corpus) CurrentSourceRevision 

func (c *Corpus) CurrentSourceRevision(ctx context.Context, subject evidence.SourceSubject) (*evidence.SourceRevision, error)

CurrentSourceRevision returns the winning local revision for one evidence subject. It performs only SQLite reads.

func (*Corpus) DeleteJobOwner 

func (c *Corpus) DeleteJobOwner(ctx context.Context, ownerID string) error

DeleteJobOwner removes a process owner record.

func (*Corpus) EnqueueFrontierItem 

func (c *Corpus) EnqueueFrontierItem(ctx context.Context, item FrontierItem) (*FrontierItem, bool, error)

EnqueueFrontierItem inserts work once. Replaying the same WorkKey returns the existing item without resetting attempts or terminal state.

func (*Corpus) ExportLocalMetadata 

func (c *Corpus) ExportLocalMetadata(ctx context.Context, opts tracking.ExportOptions) (*tracking.Bundle, error)

ExportLocalMetadata returns a redacted, deterministic snapshot of tracking metadata bounded by opts.Limit.

func (*Corpus) FailFrontierItem 

func (c *Corpus) FailFrontierItem(ctx context.Context, id int64, worker, failureKind, message string, now time.Time) error

FailFrontierItem marks a leased item terminally failed.

func (*Corpus) FailRun 

func (c *Corpus) FailRun(ctx context.Context, id int64, message string) error

FailRun marks a run as failed and stores an error message.

func (*Corpus) FindPortfolioOverlaps added in v0.6.0 

func (c *Corpus) FindPortfolioOverlaps(ctx context.Context, candidates []PortfolioSubject, pullRequestThreadIDs []int64) ([]PortfolioOverlapResult, error)

FindPortfolioOverlaps compares candidates with exact authored PR corpus IDs. It is an offline read and preserves candidate input order.

func (*Corpus) FindRelated 

func (c *Corpus) FindRelated(ctx context.Context, ref domain.RepoRef, category investigation.Category) ([]domain.SourceRef, error)

FindRelated returns stored source references related to a repository and category.

func (*Corpus) FindThreadSearchEvidence added in v0.8.0 

func (c *Corpus) FindThreadSearchEvidence(ctx context.Context, threadID int64, query string) (ThreadSearchEvidence, bool, error)

FindThreadSearchEvidence returns the best stored document matching query for one thread. It reads only the local FTS projections.

func (*Corpus) FinishRun 

func (c *Corpus) FinishRun(ctx context.Context, id int64, stats string) error

FinishRun marks a run as completed with optional statistics.

func (*Corpus) FinishRunPartial 

func (c *Corpus) FinishRunPartial(ctx context.Context, id int64, stats, message string) error

FinishRunPartial records a completed run that made progress but encountered retryable gaps.

func (*Corpus) GetClusterProjection added in v0.8.0 

func (c *Corpus) GetClusterProjection(ctx context.Context, stableID string) (*clustering.Cluster, error)

GetClusterProjection reads one cluster and its members from one read-only snapshot.

func (*Corpus) GetClusterProjectionForMember added in v0.8.0 

func (c *Corpus) GetClusterProjectionForMember(ctx context.Context, ref clustering.MemberRef) (*clustering.Cluster, error)

GetClusterProjectionForMember reads the current included cluster containing ref.

func (*Corpus) GetCodeDocument 

func (c *Corpus) GetCodeDocument(ctx context.Context, ref domain.RepoRef, path string) (*CodeMatch, error)

GetCodeDocument returns a single code document from the latest snapshot of a repository, or nil when no snapshot or document exists.

func (*Corpus) GetCollection 

func (c *Corpus) GetCollection(ctx context.Context, name string) (*Collection, error)

GetCollection returns a named collection and its current member count.

func (*Corpus) GetContribution 

func (c *Corpus) GetContribution(ctx context.Context, id string) (*tracking.Contribution, error)

GetContribution returns a contribution by durable id.

func (*Corpus) GetCoverage 

func (c *Corpus) GetCoverage(ctx context.Context, repoID int64, threadID *int64, facet string) (*Coverage, error)

GetCoverage returns the coverage fact for a single facet.

func (*Corpus) GetDiscoverySource 

func (c *Corpus) GetDiscoverySource(ctx context.Context, name string) (*DiscoverySource, error)

GetDiscoverySource returns a named source or nil.

func (*Corpus) GetDossier 

func (c *Corpus) GetDossier(ctx context.Context, owner, name string) (*DossierRecord, []DossierSource, error)

GetDossier returns the most recent persisted dossier for a repository, including its exact source set.

func (*Corpus) GetFrontierItem 

func (c *Corpus) GetFrontierItem(ctx context.Context, workKey string) (*FrontierItem, error)

GetFrontierItem returns work by its stable key, or nil when absent.

func (*Corpus) GetHypothesis 

func (c *Corpus) GetHypothesis(ctx context.Context, id string) (*investigation.Hypothesis, error)

GetHypothesis returns a hypothesis by ID, or nil when absent.

func (*Corpus) GetInvestigation 

func (c *Corpus) GetInvestigation(ctx context.Context, id string) (*investigation.Investigation, error)

GetInvestigation returns an investigation by ID, or nil when absent.

func (*Corpus) GetIssueDraft 

func (c *Corpus) GetIssueDraft(ctx context.Context, opportunityID string) (*contribution.IssueDraft, error)

GetIssueDraft returns the issue draft for an opportunity, or nil when absent.

func (*Corpus) GetJob 

func (c *Corpus) GetJob(ctx context.Context, id string) (*Job, error)

GetJob returns a job by opaque ID, or nil when absent.

func (*Corpus) GetLens 

func (c *Corpus) GetLens(ctx context.Context, name string) (*LensRecord, error)

GetLens returns a named lens or nil when it has not been saved.

func (*Corpus) GetOpportunity 

func (c *Corpus) GetOpportunity(ctx context.Context, id string) (*investigation.Opportunity, error)

GetOpportunity returns an opportunity with its dependencies and provenance.

func (*Corpus) GetProjectionState added in v0.9.0 

func (c *Corpus) GetProjectionState(ctx context.Context, name string) (ProjectionState, error)

GetProjectionState returns the durable state for one derived projection.

func (*Corpus) GetPullRequestDraft 

func (c *Corpus) GetPullRequestDraft(ctx context.Context, opportunityID string) (*contribution.PullRequestDraft, error)

GetPullRequestDraft returns the pull-request draft for an opportunity, or nil when absent.

func (*Corpus) GetRepository 

func (c *Corpus) GetRepository(ctx context.Context, owner, name string) (*Repository, error)

GetRepository returns the current projection of a repository, or nil if it has not been observed.

func (*Corpus) GetRepositoryByID 

func (c *Corpus) GetRepositoryByID(ctx context.Context, id int64) (*Repository, error)

GetRepositoryByID returns the current projection of a repository by id.

func (*Corpus) GetResolutionRecord added in v0.6.0 

func (c *Corpus) GetResolutionRecord(ctx context.Context, threadID int64) (*ResolutionRecord, error)

GetResolutionRecord returns the current stale-safe resolution projection.

func (*Corpus) GetRun 

func (c *Corpus) GetRun(ctx context.Context, id int64) (*Run, error)

GetRun returns a run record by id.

func (*Corpus) GetThread 

func (c *Corpus) GetThread(ctx context.Context, repoID int64, kind string, number int) (*Thread, error)

GetThread returns the current projection of a thread, or nil if it has not been observed.

func (*Corpus) GetThreadByNumber 

func (c *Corpus) GetThreadByNumber(ctx context.Context, repoID int64, number int) (*Thread, error)

GetThreadByNumber returns the current projection of a thread by repository and number, regardless of kind, or nil if it has not been observed.

func (*Corpus) GetThreadObservationRevision 

func (c *Corpus) GetThreadObservationRevision(ctx context.Context, threadID int64, sourceUpdatedAt time.Time, observationSequence int64) (*ThreadObservation, error)

GetThreadObservationRevision returns the immutable observation matching a projection revision. It lets callers bind copied projection fields to the exact observation even if a newer projection is written concurrently.

func (*Corpus) GetTime 

func (c *Corpus) GetTime(ctx context.Context, key string) (time.Time, bool, error)

GetTime implements discovery.CheckpointStore using the local corpus.

func (*Corpus) GetValidationDefinition 

func (c *Corpus) GetValidationDefinition(ctx context.Context, id string) (*evidence.ValidationDefinition, error)

GetValidationDefinition returns a validation plan by ID, or nil when absent.

func (*Corpus) GetValidationRun 

func (c *Corpus) GetValidationRun(ctx context.Context, id string) (*evidence.ValidationRun, error)

GetValidationRun returns a validation result by ID, or nil when absent.

func (*Corpus) GetWorkspace 

func (c *Corpus) GetWorkspace(ctx context.Context, id string) (*workspace.Workspace, error)

GetWorkspace returns a managed workspace by ID, or nil when absent.

func (*Corpus) HeartbeatJobOwner 

func (c *Corpus) HeartbeatJobOwner(ctx context.Context, ownerID string, t time.Time) error

HeartbeatJobOwner refreshes the lease heartbeat for an owner.

func (*Corpus) ImportLocalMetadata 

func (c *Corpus) ImportLocalMetadata(ctx context.Context, bundle *tracking.Bundle) error

ImportLocalMetadata imports a bounded bundle idempotently. All writes happen in a single transaction; any referential or database failure leaves the corpus unchanged.

func (*Corpus) Inventory added in v0.9.0 

func (c *Corpus) Inventory(ctx context.Context, owner, name string) (*RepositoryInventory, error)

Inventory returns a read-only inventory for the named repository.

func (*Corpus) IsImported 

func (c *Corpus) IsImported(ctx context.Context, hour string) (bool, error)

IsImported implements discovery.CheckpointStore for GH Archive hours.

func (*Corpus) LatestCodeSnapshot 

func (c *Corpus) LatestCodeSnapshot(ctx context.Context, ref domain.RepoRef) (*struct {
	RepoPath  string
	CommitSHA string
	CreatedAt time.Time
}, error)

LatestCodeSnapshot returns the most recently stored code snapshot for a repository, or nil if none exists.

func (*Corpus) LatestRateLimitObservations 

func (c *Corpus) LatestRateLimitObservations(ctx context.Context, limit int) ([]RateLimitObservation, error)

LatestRateLimitObservations returns the newest observation for each reported GitHub resource, ordered newest first.

func (*Corpus) LatestThreadObservation 

func (c *Corpus) LatestThreadObservation(ctx context.Context, threadID int64) (*ThreadObservation, error)

LatestThreadObservation returns the most recent observation for a thread by source time and observation sequence.

func (*Corpus) LeaseFrontierItems 

func (c *Corpus) LeaseFrontierItems(ctx context.Context, worker string, now time.Time, leaseDuration time.Duration, limit, budget int) ([]FrontierItem, error)

LeaseFrontierItems atomically claims ready work for a bounded interval. Expired leases are eligible for another worker. Higher priority wins, then earlier eligibility and insertion order.

func (*Corpus) ListClusterProjection added in v0.8.0 

func (c *Corpus) ListClusterProjection(ctx context.Context, repo domain.RepoRef, state clustering.ClusterState, limit int) (result clusterprojection.List, err error)

ListClusterProjection reads cluster headers and all returned children from a single read-only SQLite snapshot using two statements.

func (*Corpus) ListCodeDocuments 

func (c *Corpus) ListCodeDocuments(ctx context.Context, ref domain.RepoRef) ([]CodeMatch, error)

ListCodeDocuments returns all documents from the latest snapshot of a repository. Results are bounded to avoid unbounded offline work.

func (*Corpus) ListCollectionMembers 

func (c *Corpus) ListCollectionMembers(ctx context.Context, collectionName string) ([]CollectionMember, error)

ListCollectionMembers returns members in stable kind and reference order.

func (*Corpus) ListCollections 

func (c *Corpus) ListCollections(ctx context.Context) ([]Collection, error)

ListCollections returns collections in stable name order.

func (*Corpus) ListContributionOutcomes 

func (c *Corpus) ListContributionOutcomes(ctx context.Context, contributionID string) ([]*tracking.ContributionOutcome, error)

ListContributionOutcomes returns outcomes for a contribution.

func (*Corpus) ListContributions 

func (c *Corpus) ListContributions(ctx context.Context, filter tracking.ContributionFilter) ([]*tracking.Contribution, error)

ListContributions returns contributions in prepared-at order.

func (*Corpus) ListCoverage 

func (c *Corpus) ListCoverage(ctx context.Context, repoID int64, threadID *int64) ([]Coverage, error)

ListCoverage returns all coverage facts for a repository or thread.

func (*Corpus) ListDiscoverySources 

func (c *Corpus) ListDiscoverySources(ctx context.Context) ([]DiscoverySource, error)

ListDiscoverySources returns all sources in stable name order.

func (*Corpus) ListDossiers 

func (c *Corpus) ListDossiers(ctx context.Context, limit int) ([]DossierRecord, error)

ListDossiers returns the most recent dossier for each repository up to limit.

func (*Corpus) ListEvidence 

func (c *Corpus) ListEvidence(ctx context.Context, filter evidence.EvidenceFilter) (out []*evidence.Evidence, err error)

ListEvidence returns evidence matching the supplied local filter.

func (*Corpus) ListFacetObservations 

func (c *Corpus) ListFacetObservations(ctx context.Context, repoID int64, threadID *int64, facet string) ([]FacetObservation, error)

ListFacetObservations returns immutable observations for a facet, ordered by observation sequence.

func (*Corpus) ListFacetObservationsBounded 

func (c *Corpus) ListFacetObservationsBounded(ctx context.Context, repoID int64, threadID *int64, facet string, limit int) ([]FacetObservation, bool, error)

ListFacetObservationsBounded returns at most limit immutable observations and reports whether additional stored pages exist. Ordering matches ListFacetObservations. It lets offline readers enforce a memory bound before payload decoding.

func (*Corpus) ListHypotheses 

func (c *Corpus) ListHypotheses(ctx context.Context, investigationID string) ([]*investigation.Hypothesis, error)

ListHypotheses returns hypotheses belonging to an investigation.

func (*Corpus) ListInventory added in v0.9.0 

func (c *Corpus) ListInventory(ctx context.Context) (_ *InventorySummary, returnErr error)

ListInventory aggregates the corpus by repository. Its result is bounded to one row per stored repository or code-index scope, while the SQL performs grouped scans rather than loading unbounded observation detail into memory.

func (*Corpus) ListInvestigations 

func (c *Corpus) ListInvestigations(ctx context.Context) ([]*investigation.Investigation, error)

ListInvestigations returns investigations in deterministic creation order.

func (*Corpus) ListJobEvents 

func (c *Corpus) ListJobEvents(ctx context.Context, jobID string) ([]JobEvent, error)

ListJobEvents returns events for a job in chronological order.

func (*Corpus) ListJobs 

func (c *Corpus) ListJobs(ctx context.Context, status string, limit int) ([]Job, error)

ListJobs returns recent jobs bounded by limit, optionally filtered by status.

func (*Corpus) ListLenses 

func (c *Corpus) ListLenses(ctx context.Context) ([]LensRecord, error)

ListLenses returns saved lenses in stable name order.

func (*Corpus) ListOpportunities 

func (c *Corpus) ListOpportunities(ctx context.Context, investigationID string) ([]*investigation.Opportunity, error)

ListOpportunities returns opportunities belonging to an investigation. 

func (c *Corpus) ListPortfolioLinks(ctx context.Context) (out []PortfolioLink, err error)

ListPortfolioLinks returns explicit links in stable PR/opportunity/workspace order.

func (*Corpus) ListProjectionStates added in v0.9.0 

func (c *Corpus) ListProjectionStates(ctx context.Context) (_ []ProjectionState, returnErr error)

ListProjectionStates returns all durable derived-projection states. 

func (c *Corpus) ListPullRequestIssueLinks(ctx context.Context, repoID int64, state string, limit int) (out []PullRequestIssueLinks, capped bool, err error)

ListPullRequestIssueLinks returns a bounded, deterministic offline view of authoritative closing-issue relationships for stored pull requests. It performs one corpus query and preserves selected-thread ordering.

func (*Corpus) ListPullRequestPortfolio added in v0.5.0 

func (c *Corpus) ListPullRequestPortfolio(ctx context.Context, author, state string, limit int) (_ []PortfolioPullRequest, err error)

ListPullRequestPortfolio returns pull requests across all stored repositories. Author login and state are optional, case-insensitive filters; state "all" is equivalent to no state filter. The read is bounded and deterministic so callers can build portfolio views without repository-level N+1 queries.

func (*Corpus) ListRepositories 

func (c *Corpus) ListRepositories(ctx context.Context, query string, limit int) ([]Repository, error)

ListRepositories returns repositories matching an optional name query. An empty query lists all repositories ordered by most recently updated.

func (*Corpus) ListRepositoriesWithOptions 

func (c *Corpus) ListRepositoriesWithOptions(ctx context.Context, query string, opts RepositorySearchOptions) (RepositorySearchPage, error)

ListRepositoriesWithOptions returns repositories matching an optional name query with stable cursor pagination. Results are ordered by source_updated_at descending, then id descending, so the same cursor always returns the same next page on an unchanged corpus.

func (*Corpus) ListRepositoryObservations 

func (c *Corpus) ListRepositoryObservations(ctx context.Context, repoID int64) ([]RepositoryObservation, error)

ListRepositoryObservations returns immutable observations for a repository in insertion order.

func (*Corpus) ListRunEvents 

func (c *Corpus) ListRunEvents(ctx context.Context, runID int64) ([]RunEvent, error)

ListRunEvents returns events for a run in chronological order.

func (*Corpus) ListRuns 

func (c *Corpus) ListRuns(ctx context.Context, limit int) ([]Run, error)

ListRuns returns the most recent run records bounded by limit.

func (*Corpus) ListThreadObservations 

func (c *Corpus) ListThreadObservations(ctx context.Context, threadID int64) ([]ThreadObservation, error)

ListThreadObservations returns immutable observations for a thread in insertion order.

func (*Corpus) ListThreads 

func (c *Corpus) ListThreads(ctx context.Context, repoID int64, kind string, limit int) ([]Thread, error)

ListThreads returns threads for a repository, optionally filtered by kind, ordered by source update time descending and then number descending.

func (*Corpus) ListThreadsFiltered 

func (c *Corpus) ListThreadsFiltered(ctx context.Context, repoID int64, kind, state string, limit int) ([]Thread, error)

ListThreadsFiltered returns threads for a repository, optionally filtered by kind and state, ordered by source update time descending and then number descending. Filtering happens at the corpus boundary before any limit is applied, so bounded callers do not silently drop matching rows.

func (*Corpus) ListTriageEvents 

func (c *Corpus) ListTriageEvents(ctx context.Context, filter tracking.TriageEventFilter) ([]*tracking.TriageEvent, error)

ListTriageEvents returns triage events in source-event order.

func (*Corpus) ListValidationDefinitions 

func (c *Corpus) ListValidationDefinitions(ctx context.Context, opportunityID string) ([]*evidence.ValidationDefinition, error)

ListValidationDefinitions returns validation plans scoped to an opportunity.

func (*Corpus) ListValidationRuns 

func (c *Corpus) ListValidationRuns(ctx context.Context, opportunityID string) ([]*evidence.ValidationRun, error)

ListValidationRuns returns validation runs scoped to an opportunity.

func (*Corpus) LoadClusterRefreshSnapshot added in v0.8.0 

func (c *Corpus) LoadClusterRefreshSnapshot(ctx context.Context, repo domain.RepoRef, maxCandidates int) (result clusterprojection.RefreshSnapshot, err error)

LoadClusterRefreshSnapshot reads every input needed by a refresh from one SQLite snapshot and closes the transaction before CPU-heavy pair evaluation.

func (*Corpus) LoadPrecedentRepositories added in v0.8.0 

func (c *Corpus) LoadPrecedentRepositories(ctx context.Context, refs []precedent.SourceRef, closedLimit int) (result []precedent.RepositorySnapshot, err error)

LoadPrecedentRepositories loads each unique repository once, batches all requested source numbers for it, and loads its bounded closed history once. The returned snapshots follow first repository appearance in refs.

func (*Corpus) MarkImported 

func (c *Corpus) MarkImported(ctx context.Context, hour string) error

MarkImported records an imported GH Archive hour idempotently.

func (*Corpus) PlanCodeSnapshotPrune added in v0.9.0 

func (c *Corpus) PlanCodeSnapshotPrune(ctx context.Context, ref domain.RepoRef, keepLatest int) (*CodeSnapshotPrunePlan, error)

PlanCodeSnapshotPrune returns a dry-run plan that would keep the latest N derived code snapshots for a repository and delete the rest.

func (*Corpus) PlanRepositoryRemoval added in v0.9.0 

func (c *Corpus) PlanRepositoryRemoval(ctx context.Context, ref domain.RepoRef) (plan *RepositoryRemovalPlan, err error)

PlanRepositoryRemoval previews removal without mutating the corpus.

func (*Corpus) PromoteHypothesis 

func (c *Corpus) PromoteHypothesis(ctx context.Context, hypothesis *investigation.Hypothesis, opportunity *investigation.Opportunity) error

PromoteHypothesis atomically stores the promoted hypothesis and its new opportunity so a partial write cannot strand the hypothesis.

func (*Corpus) PromoteHypothesisWithEvidence 

func (c *Corpus) PromoteHypothesisWithEvidence(ctx context.Context, hypothesis *investigation.Hypothesis, opportunity *investigation.Opportunity, item *evidence.Evidence) error

PromoteHypothesisWithEvidence stores an optional promotion evidence record in the same transaction as the promoted hypothesis and opportunity.

func (*Corpus) RebuildCodeSearchProjection added in v0.9.0 

func (c *Corpus) RebuildCodeSearchProjection(ctx context.Context) (ProjectionState, error)

RebuildCodeSearchProjection atomically rebuilds the code_documents_fts index and advances the durable projection state. It is explicit: search never calls it.

func (*Corpus) RebuildFacetSearchProjection added in v0.9.0 

func (c *Corpus) RebuildFacetSearchProjection(ctx context.Context) (ProjectionState, error)

RebuildFacetSearchProjection atomically rebuilds searchable hydrated facet evidence. Thread search requires both thread and facet projections.

func (*Corpus) RebuildThreadSearchProjection added in v0.9.0 

func (c *Corpus) RebuildThreadSearchProjection(ctx context.Context) (ProjectionState, error)

RebuildThreadSearchProjection atomically rebuilds the threads_fts index and advances the durable projection state. It is explicit: search never calls it.

func (*Corpus) ReconcileInterruptedJobs 

func (c *Corpus) ReconcileInterruptedJobs(ctx context.Context, leaseTimeout time.Duration) error

ReconcileInterruptedJobs marks running jobs as failed or cancelled when their owning process has not heartbeated within leaseTimeout. Live owners are left untouched, and stale owner records are removed.

It uses BEGIN IMMEDIATE so the write lock is acquired before any reads, avoiding a lock-upgrade race with concurrent heartbeats.

func (*Corpus) RecordContributionOutcome 

func (c *Corpus) RecordContributionOutcome(ctx context.Context, o *tracking.ContributionOutcome) error

RecordContributionOutcome stores a lifecycle event for a contribution.

func (*Corpus) RecordJobEvent 

func (c *Corpus) RecordJobEvent(ctx context.Context, jobID, level, message string) error

RecordJobEvent appends a durable event to a job.

func (*Corpus) RecordRateLimitObservation 

func (c *Corpus) RecordRateLimitObservation(ctx context.Context, observation RateLimitObservation) error

RecordRateLimitObservation stores one bounded, redacted request observation.

func (*Corpus) RecordRunEvent 

func (c *Corpus) RecordRunEvent(ctx context.Context, runID int64, level, message string) error

RecordRunEvent appends a durable event to a run.

func (*Corpus) RecordSourcePartition 

func (c *Corpus) RecordSourcePartition(ctx context.Context, partition SourcePartition) error

RecordSourcePartition upserts the latest observation for one stable window.

func (*Corpus) RecordTriageEvent 

func (c *Corpus) RecordTriageEvent(ctx context.Context, e *tracking.TriageEvent) error

RecordTriageEvent stores a triage event with optional foreign-key-safe links.

func (*Corpus) RefreshDossier 

func (c *Corpus) RefreshDossier(ctx context.Context, repoID int64, owner, name, commitSHA string, asOf time.Time, sectionMetadata, snapshot string, generatedAt time.Time, sources []domain.SourceRef) (int64, bool, error)

RefreshDossier stores a dossier only when it is newer than the latest stored snapshot for the repository, or has changed at the same as-of time. It returns the dossier id and whether a new row was inserted.

func (*Corpus) RegisterJobOwner 

func (c *Corpus) RegisterJobOwner(ctx context.Context, ownerID string, processID int, t time.Time) error

RegisterJobOwner records a process owner with an explicit heartbeat time. Calling it again for an existing owner updates its process_id and heartbeat.

func (*Corpus) ReleaseFrontierItem 

func (c *Corpus) ReleaseFrontierItem(ctx context.Context, id int64, worker string, now time.Time) error

ReleaseFrontierItem returns leased but unstarted work to the queue. Because leasing increments attempts, releasing unstarted work refunds that attempt. Only the current lease owner can release the item.

func (*Corpus) ReplacePortfolioSignals added in v0.6.0 

func (c *Corpus) ReplacePortfolioSignals(ctx context.Context, snapshot PortfolioSignalSnapshot) (saved *PortfolioSignalSnapshot, err error)

ReplacePortfolioSignals stores a complete child snapshot and atomically advances its projection only if its source clock is newer.

func (*Corpus) RequestJobCancellation 

func (c *Corpus) RequestJobCancellation(ctx context.Context, id string) error

RequestJobCancellation records a cancellation request. Queued jobs are moved directly to cancelled; running jobs have cancelled_at set so that they finish as cancelled.

func (*Corpus) RequireProjection added in v0.9.0 

func (c *Corpus) RequireProjection(ctx context.Context, name, version string) error

RequireProjection verifies that a read can consume the named derived projection. It never rebuilds or mutates projection state.

func (*Corpus) RetryFrontierItem 

func (c *Corpus) RetryFrontierItem(ctx context.Context, id int64, worker, message string, earliestRunAt, now time.Time) error

RetryFrontierItem releases leased work after a transient failure. Once the attempt limit is reached, the item becomes terminally failed.

func (*Corpus) SaveCollection 

func (c *Corpus) SaveCollection(ctx context.Context, name string) (*Collection, error)

SaveCollection creates a named collection or returns its existing identity.

func (*Corpus) SaveContribution 

func (c *Corpus) SaveContribution(ctx context.Context, item *tracking.Contribution) error

SaveContribution stores contribution metadata separate from GitHub state.

func (*Corpus) SaveDiscoverySource 

func (c *Corpus) SaveDiscoverySource(ctx context.Context, source DiscoverySource) (*DiscoverySource, error)

SaveDiscoverySource creates or updates a named source definition.

func (*Corpus) SaveDossier 

func (c *Corpus) SaveDossier(ctx context.Context, repoID int64, owner, name, commitSHA string, asOf time.Time, sectionMetadata, snapshot string, generatedAt time.Time, sources []domain.SourceRef) (int64, error)

SaveDossier persists a deterministic dossier snapshot and its exact sources.

func (*Corpus) SaveEvidence 

func (c *Corpus) SaveEvidence(ctx context.Context, item *evidence.Evidence) error

SaveEvidence inserts or updates an evidence record and its provenance.

func (*Corpus) SaveHypothesis 

func (c *Corpus) SaveHypothesis(ctx context.Context, item *investigation.Hypothesis) error

SaveHypothesis inserts or updates a hypothesis and its structured fields.

func (*Corpus) SaveInvestigation 

func (c *Corpus) SaveInvestigation(ctx context.Context, item *investigation.Investigation) error

SaveInvestigation inserts or updates an investigation record.

func (*Corpus) SaveIssueDraft 

func (c *Corpus) SaveIssueDraft(ctx context.Context, item *contribution.IssueDraft) error

SaveIssueDraft persists the latest rendered issue draft for an opportunity.

func (*Corpus) SaveLens 

func (c *Corpus) SaveLens(ctx context.Context, definition lens.Definition) (*LensRecord, error)

SaveLens creates or replaces a named lens after validating its scoring contract. Existing creation time is retained.

func (*Corpus) SaveOpportunity 

func (c *Corpus) SaveOpportunity(ctx context.Context, item *investigation.Opportunity) error

SaveOpportunity atomically persists an opportunity and its dependencies and source references. 

func (c *Corpus) SavePortfolioLink(ctx context.Context, link PortfolioLink) (*PortfolioLink, error)

SavePortfolioLink idempotently records an explicit local workflow link.

func (*Corpus) SavePullRequestDraft 

func (c *Corpus) SavePullRequestDraft(ctx context.Context, item *contribution.PullRequestDraft) error

SavePullRequestDraft persists the latest pull-request draft for an opportunity.

func (*Corpus) SaveResolutionRecord added in v0.6.0 

func (c *Corpus) SaveResolutionRecord(ctx context.Context, record ResolutionRecord) (saved *ResolutionRecord, err error)

SaveResolutionRecord appends a derivation and advances the current projection only when its source clock is newer.

func (*Corpus) SaveValidationDefinition 

func (c *Corpus) SaveValidationDefinition(ctx context.Context, item *evidence.ValidationDefinition) error

SaveValidationDefinition persists a validation plan without executing it.

func (*Corpus) SaveValidationRun 

func (c *Corpus) SaveValidationRun(ctx context.Context, item *evidence.ValidationRun) error

SaveValidationRun persists the bounded result of an authorized validation execution.

func (*Corpus) SaveWorkspace 

func (c *Corpus) SaveWorkspace(ctx context.Context, item *workspace.Workspace) error

SaveWorkspace inserts or replaces a managed workspace record.

func (*Corpus) SchemaVersion 

func (c *Corpus) SchemaVersion(ctx context.Context) (int64, error)

SchemaVersion returns the applied Goose schema version.

func (*Corpus) SchemaVersions added in v0.7.1 

func (c *Corpus) SchemaVersions(ctx context.Context) (current, target int64, err error)

SchemaVersions returns the current database version and the latest version supported by this binary.

func (*Corpus) SearchCode 

func (c *Corpus) SearchCode(ctx context.Context, query string, ref domain.RepoRef, limit int) ([]CodeMatch, error)

SearchCode searches only the latest indexed snapshot of each repository.

func (*Corpus) SearchCodeWithOptions 

func (c *Corpus) SearchCodeWithOptions(ctx context.Context, query string, opts CodeSearchOptions) (CodeSearchPage, error)

SearchCodeWithOptions searches only the latest indexed snapshot of each repository with stable cursor pagination. Results are ordered by FTS5 rank ascending, then document id ascending. No network access occurs.

func (*Corpus) SearchThreads 

func (c *Corpus) SearchThreads(ctx context.Context, query string, limit int) ([]Thread, error)

SearchThreads performs an FTS5 keyword search over thread title, body, and searchable hydrated facet evidence. It returns matching threads ordered by FTS5 rank and limited to at most limit results. No network access occurs.

func (*Corpus) SearchThreadsPage 

func (c *Corpus) SearchThreadsPage(ctx context.Context, query string, filter SearchFilter) (ThreadSearchPage, error)

SearchThreadsPage performs an FTS5 keyword search with stable cursor pagination. Results are ordered by FTS5 rank ascending, then thread id ascending, so the same cursor always returns the same next page on an unchanged corpus. No network access occurs.

func (*Corpus) SearchThreadsWithFilter 

func (c *Corpus) SearchThreadsWithFilter(ctx context.Context, query string, filter SearchFilter) ([]Thread, error)

SearchThreadsWithFilter performs the same search as SearchThreads but supports filtering to a repository and thread kind.

func (*Corpus) SetTime 

func (c *Corpus) SetTime(ctx context.Context, key string, checkpoint time.Time) error

SetTime atomically advances a discovery timestamp checkpoint. Older replayed checkpoints cannot move it backwards.

func (*Corpus) StartJob 

func (c *Corpus) StartJob(ctx context.Context, id string) error

StartJob atomically transitions a queued job to running without an owner.

func (*Corpus) StartJobAs 

func (c *Corpus) StartJobAs(ctx context.Context, id, ownerID string) error

StartJobAs atomically transitions a queued job to running and claims it for the given owner. An empty ownerID leaves owner_id NULL.

func (*Corpus) StartRun 

func (c *Corpus) StartRun(ctx context.Context, kind string) (*Run, error)

StartRun creates and returns a new run record in the running state.

func (*Corpus) StartThreadInvestigation 

func (c *Corpus) StartThreadInvestigation(ctx context.Context, item *investigation.Investigation, hypothesis *investigation.Hypothesis) (_ *investigation.Investigation, _ *investigation.Hypothesis, _ bool, returnErr error)

StartThreadInvestigation atomically inserts an investigation and its seed hypothesis. If the same thread already has an open investigation, the stored pair is returned without changing its original baseline.

func (*Corpus) Status 

func (c *Corpus) Status(ctx context.Context) (Status, error)

Status returns the number of repositories and threads in the corpus.

func (*Corpus) StoreCodeSnapshot 

func (c *Corpus) StoreCodeSnapshot(ctx context.Context, ref domain.RepoRef, snapshot codeindex.Snapshot) (int64, bool, error)

StoreCodeSnapshot atomically stores one complete immutable code snapshot. Replaying the same repository commit returns the existing snapshot id.

func (*Corpus) TransitionJob 

func (c *Corpus) TransitionJob(ctx context.Context, id, from, to, result, errStr string) error

TransitionJob performs a safe atomic terminal transition for a job. The current status must match from, and cancellation requests block transitions to non-cancelled terminal states. Terminal transitions clear the owner.

func (*Corpus) UpdateJobProgress 

func (c *Corpus) UpdateJobProgress(ctx context.Context, id, progress, statistics string) error

UpdateJobProgress updates progress and statistics for a running job.

func (*Corpus) UpsertRepository 

func (c *Corpus) UpsertRepository(ctx context.Context, repo Repository, payload string) (*Repository, error)

UpsertRepository records a repository observation and updates the projection with all fields when the source ordering is newer.

func (*Corpus) UpsertThread 

func (c *Corpus) UpsertThread(ctx context.Context, thread Thread, payload string) (*Thread, error)

UpsertThread records a thread observation and updates the projection with all fields when the source ordering is newer.

type Coverage 

type Coverage struct {
	ID                  int64
	RepositoryID        int64
	ThreadID            *int64
	Facet               string
	SourceUpdatedAt     time.Time
	ObservationSequence int64
	Complete            bool
	RunID               *int64
	UpdatedAt           time.Time
}

Coverage records which hydration facet has been fetched for a repository or thread and whether it is complete. Each facet advances independently under the same source_updated_at/observation_sequence ordering as projections.

type DiscoverySource 

type DiscoverySource struct {
	ID         int64
	Name       string
	Kind       string
	Definition string
	Enabled    bool
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

DiscoverySource is one durable repository-discovery definition.

type DossierRecord 

type DossierRecord struct {
	ID              int64
	RepositoryID    int64
	RepoOwner       string
	RepoName        string
	CommitSHA       string
	AsOf            time.Time
	SectionMetadata string
	Snapshot        string
	GeneratedAt     time.Time
	CreatedAt       time.Time
}

DossierRecord is a persisted deterministic dossier snapshot.

type DossierSource 

type DossierSource struct {
	ID         int64
	DossierID  int64
	Source     string
	URL        string
	CommitSHA  string
	ObservedAt time.Time
	AsOf       time.Time
}

DossierSource is one exact source recorded for a dossier.

type FacetObservation 

type FacetObservation struct {
	ID                  int64
	RepositoryID        int64
	ThreadID            *int64
	Facet               string
	SourceUpdatedAt     time.Time
	ObservationSequence int64
	Payload             string
	ObservedAt          time.Time
}

FacetObservation is an immutable snapshot of a thread facet (comments, reviews, review comments, or PR details) received from a source.

type FacetObservationInput 

type FacetObservationInput struct {
	SourceUpdatedAt time.Time
	Payload         string
	// SearchText is optional product-selected untrusted text. Callers collapse
	// transport pages into one semantic search document.
	SearchText string
}

FacetObservationInput is an unpersisted facet observation page.

type FrontierItem 

type FrontierItem struct {
	ID             int64
	WorkKey        string
	SubjectKind    string
	Owner          string
	Repo           string
	ThreadKind     string
	ThreadNumber   int
	Facet          string
	Priority       int
	Reason         string
	Source         string
	Attempts       int
	MaxAttempts    int
	EarliestRunAt  time.Time
	BudgetEstimate int
	State          string
	LeaseOwner     string
	LeaseExpiresAt *time.Time
	FailureKind    string
	LastError      string
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

FrontierItem is a deduplicated unit of repository, thread, or facet work. WorkKey is a stable product-owned identity chosen by the caller.

type InventorySummary added in v0.9.0 

type InventorySummary struct {
	Repositories []RepositoryInventory

	ObservationPayloadBytes int64
	CodeBytes               int64
	DBSize                  int64
	WALSize                 int64
	TotalSize               int64
}

InventorySummary is a bounded, read-only summary of every repository-shaped scope in the corpus. Repository rows and code-only scopes are both included; individual observations and documents are never returned.

type Job 

type Job struct {
	ID          string
	Kind        string
	Status      string
	Request     string
	Result      string
	Error       string
	Progress    string
	Statistics  string
	CreatedAt   time.Time
	StartedAt   *time.Time
	CompletedAt *time.Time
	UpdatedAt   time.Time
	CancelledAt *time.Time
}

Job is a durable, cancellable unit of work.

type JobEvent 

type JobEvent struct {
	ID         int64
	JobID      string
	Level      string
	Message    string
	RecordedAt time.Time
}

JobEvent is a durable log line emitted during a job.

type LensRecord 

type LensRecord struct {
	Definition lens.Definition
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

LensRecord is a durable, reusable ranking definition.

type MigrationObserver added in v0.9.0 

type MigrationObserver func(MigrationProgress)

MigrationObserver receives explicit migration progress updates.

type MigrationProgress added in v0.9.0 

type MigrationProgress struct {
	Phase   string
	Version int64
	Name    string
	Current int64
	Target  int64
}

MigrationProgress reports stable step boundaries. SQL migration internals remain owned by Goose; data-sized migrations should expose their own bounded checkpoints rather than pretending statement-level progress is available.

type MigrationRequiredError added in v0.9.0 

type MigrationRequiredError struct {
	Current int64
	Target  int64
}

MigrationRequiredError reports that a corpus must be migrated before the requested operation can use the current schema. Read-only callers can inspect this error without granting migration authority.

func (*MigrationRequiredError) Error added in v0.9.0 

func (e *MigrationRequiredError) Error() string

type MigrationStep added in v0.9.0 

type MigrationStep struct {
	Version           int64
	Name              string
	AffectedRows      int64
	EstimateAvailable bool
	Transactional     bool
	Resumable         bool
	ResumeStrategy    string
	ProjectionRebuild bool
}

MigrationStep describes one embedded schema migration without applying it.

type ObservationRef added in v0.6.0 

type ObservationRef struct {
	Kind string `json:"kind"`
	ID   int64  `json:"id"`
}

ObservationRef identifies one immutable corpus observation used to derive a local portfolio or resolution fact. Kind is product-owned (for example, thread or facet) and ID is the corresponding corpus observation identity. 

type PortfolioLink struct {
	ID                  int64     `json:"id"`
	PullRequestThreadID int64     `json:"pull_request_thread_id"`
	OpportunityID       string    `json:"opportunity_id,omitempty"`
	WorkspaceID         string    `json:"workspace_id,omitempty"`
	CreatedAt           time.Time `json:"created_at"`
}

PortfolioLink explicitly associates an authored PR with local workflow state. OpportunityID or WorkspaceID, and possibly both, must be present.

type PortfolioOverlapEvidence added in v0.6.0 

type PortfolioOverlapEvidence struct {
	Kind                  string           `json:"kind"`
	Value                 string           `json:"value"`
	Score                 float64          `json:"score,omitempty"`
	SourceObservationRefs []ObservationRef `json:"source_observation_refs"`
}

PortfolioOverlapEvidence is an exact observed reason for an overlap.

type PortfolioOverlapMatch added in v0.6.0 

type PortfolioOverlapMatch struct {
	PullRequestThreadID int64                      `json:"pull_request_thread_id"`
	Evidence            []PortfolioOverlapEvidence `json:"evidence"`
}

PortfolioOverlapMatch associates one candidate with an authored PR.

type PortfolioOverlapResult added in v0.6.0 

type PortfolioOverlapResult struct {
	Candidate PortfolioSubject        `json:"candidate"`
	Status    string                  `json:"status"`
	Coverage  map[string]string       `json:"coverage"`
	Matches   []PortfolioOverlapMatch `json:"matches"`
}

PortfolioOverlapResult preserves candidate input order. Status is overlap, no_overlap, or unknown. A no_overlap result requires complete coverage of every overlap facet for both the candidate and every compared PR.

type PortfolioPullRequest added in v0.5.0 

type PortfolioPullRequest struct {
	Owner  string
	Repo   string
	Thread Thread
}

PortfolioPullRequest identifies a pull request together with the repository that owns it. It is returned by global, offline portfolio reads.

type PortfolioSignal added in v0.6.0 

type PortfolioSignal struct {
	Kind       string  `json:"kind"`
	Value      string  `json:"value"`
	TargetKind string  `json:"target_kind,omitempty"`
	TargetRef  string  `json:"target_ref,omitempty"`
	Score      float64 `json:"score,omitempty"`
}

PortfolioSignal is one normalized overlap input. Similarity signals name a target subject and carry a score; path and linked-issue signals use Value.

type PortfolioSignalSnapshot added in v0.6.0 

type PortfolioSignalSnapshot struct {
	ID                    int64             `json:"id"`
	Subject               PortfolioSubject  `json:"subject"`
	Facet                 string            `json:"facet"`
	Signals               []PortfolioSignal `json:"signals"`
	SourceUpdatedAt       time.Time         `json:"source_updated_at"`
	ObservationSequence   int64             `json:"observation_sequence"`
	SourceObservationRefs []ObservationRef  `json:"source_observation_refs"`
	ObservedAt            time.Time         `json:"observed_at"`
}

PortfolioSignalSnapshot is one complete, immutable facet replacement.

type PortfolioSubject added in v0.6.0 

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

PortfolioSubject is a stable local identity. Pull-request references are decimal corpus thread IDs; opportunity and workspace references are IDs.

type PostCommitCleanupError added in v0.9.0 

type PostCommitCleanupError struct {
	Err error
}

PostCommitCleanupError indicates that restore committed successfully but a private staging artifact could not be cleaned up.

func (*PostCommitCleanupError) Error added in v0.9.0 

func (e *PostCommitCleanupError) Error() string

func (*PostCommitCleanupError) Unwrap added in v0.9.0 

func (e *PostCommitCleanupError) Unwrap() error

Unwrap returns the cleanup failure.

type ProjectionAttemptStatus added in v0.9.0 

type ProjectionAttemptStatus string

ProjectionAttemptStatus describes the most recent explicit rebuild attempt. 

const (
	// ProjectionAttemptNone indicates that no explicit rebuild has been attempted.
	ProjectionAttemptNone ProjectionAttemptStatus = ""
	// ProjectionAttemptBuilding indicates that a rebuild is in progress.
	ProjectionAttemptBuilding ProjectionAttemptStatus = "building"
	// ProjectionAttemptSucceeded indicates that a rebuild completed successfully.
	ProjectionAttemptSucceeded ProjectionAttemptStatus = "succeeded"
	// ProjectionAttemptFailed indicates that a rebuild failed.
	ProjectionAttemptFailed ProjectionAttemptStatus = "failed"
)

type ProjectionState added in v0.9.0 

type ProjectionState struct {
	Name              string
	Version           string
	Status            ProjectionStatus
	RefreshedAt       time.Time
	RowCount          int64
	SourceRevision    string
	ContentHash       string
	AttemptStatus     ProjectionAttemptStatus
	AttemptStartedAt  time.Time
	AttemptFinishedAt time.Time
	AttemptError      string
}

ProjectionState is the durable identity and freshness of a derived SQLite projection. It is owned by the corpus and read by offline search readers.

type ProjectionStatus added in v0.9.0 

type ProjectionStatus string

ProjectionStatus describes the durability state of a derived projection. 

const (
	// ProjectionStatusAbsent indicates that a derived projection is not built.
	ProjectionStatusAbsent ProjectionStatus = "absent"
	// ProjectionStatusBuilding indicates that a projection build is in progress.
	ProjectionStatusBuilding ProjectionStatus = "building"
	// ProjectionStatusCurrent indicates that the projection matches its source.
	ProjectionStatusCurrent ProjectionStatus = "current"
	// ProjectionStatusStale indicates that the projection source has changed.
	ProjectionStatusStale ProjectionStatus = "stale"
	// ProjectionStatusFailed indicates that the latest projection build failed.
	ProjectionStatusFailed ProjectionStatus = "failed"
)
type PullRequestIssueLinks struct {
	ThreadID              int64
	Number                int
	Covered               bool
	LinkedIssues          []string
	SourceUpdatedAt       time.Time
	SourceObservationRefs []ObservationRef
}

PullRequestIssueLinks is the latest complete linked-issue projection for one stored pull request. Covered distinguishes an observed empty relationship set from a facet that has never completed.

type RateLimitObservation 

type RateLimitObservation struct {
	Attempt    int
	StatusCode int
	Resource   string
	Limit      int
	Remaining  int
	Used       int
	ResetAt    time.Time
	Delay      time.Duration
	APIVersion string
	SourceURL  string
	ObservedAt time.Time
}

RateLimitObservation is a redacted GitHub request/rate-limit measurement.

type Repository 

type Repository struct {
	ID                  int64
	Owner               string
	Name                string
	ExternalID          string
	Description         string
	DefaultBranch       string
	Language            string
	License             string
	Topics              []string
	Stars               int
	Watchers            int
	Forks               int
	OpenIssues          int
	Archived            bool
	Fork                bool
	SourceCreatedAt     time.Time
	SourceUpdatedAt     time.Time
	ObservationSequence int64
	CreatedAt           time.Time
	UpdatedAt           time.Time
}

Repository is the current projection of a GitHub repository.

type RepositoryInventory added in v0.9.0 

type RepositoryInventory struct {
	RepoOwner string
	RepoName  string

	Issues       int
	PullRequests int
	Threads      int

	RepositoryObservations int
	ThreadObservations     int
	FacetObservations      int
	FacetCoverage          int
	TotalObservations      int

	CodeSnapshots int
	CodeDocuments int
	CodeBytes     int64

	LatestObservationAt time.Time

	DBSize    int64
	WALSize   int64
	TotalSize int64
}

RepositoryInventory is a read-only summary of one repository in the corpus. It counts durable observations, derived projections, and code snapshots.

type RepositoryObservation 

type RepositoryObservation struct {
	ID                  int64
	RepositoryID        int64
	SourceUpdatedAt     time.Time
	ObservationSequence int64
	Payload             string
	ObservedAt          time.Time
}

RepositoryObservation is an immutable snapshot received from a source.

type RepositoryRemovalPlan added in v0.9.0 

type RepositoryRemovalPlan struct {
	Ref                          domain.RepoRef
	RepositoryID                 int64
	Revision                     string
	RepositoryObservations       int
	Threads                      int
	ThreadObservations           int
	FacetObservations            int
	FacetCoverage                int
	CodeSnapshots                int
	CodeDocuments                int
	Dossiers                     int
	ClusterRuns                  int
	Clusters                     int
	FrontierItems                int
	DetachedTriageEvents         int
	RemovedPortfolioLinks        int
	RemovedResolutionRecords     int
	RemovedSignalSnapshots       int
	DetachedClusterMembers       int
	PreservedInvestigations      int
	PreservedCrossRepoReferences int
}

RepositoryRemovalPlan is an exact, non-mutating preview of repository-owned durable observations and derived data. Local workflow records are preserved because investigations, opportunities, and workspaces may span repositories.

type RepositoryRemovalResult added in v0.9.0 

type RepositoryRemovalResult struct {
	Plan *RepositoryRemovalPlan
}

RepositoryRemovalResult reports the exact plan that was applied.

type RepositorySearchOptions 

type RepositorySearchOptions struct {
	Limit  int
	Cursor string
}

RepositorySearchOptions scopes a paginated repository search.

type RepositorySearchPage 

type RepositorySearchPage struct {
	Repositories []Repository
	NextCursor   string
	Total        int
}

RepositorySearchPage is a paginated result of a repository keyword search.

type ResolutionRecord added in v0.6.0 

type ResolutionRecord struct {
	ID                    int64            `json:"id"`
	ThreadID              int64            `json:"thread_id"`
	Kind                  string           `json:"kind"`
	Summary               string           `json:"summary"`
	RuleVersion           string           `json:"rule_version"`
	SourceUpdatedAt       time.Time        `json:"source_updated_at"`
	ObservationSequence   int64            `json:"observation_sequence"`
	SourceObservationRefs []ObservationRef `json:"source_observation_refs"`
	DerivedAt             time.Time        `json:"derived_at"`
}

ResolutionRecord is a deterministic local derivation over immutable source observations. It is not a root-cause claim and must identify its rule set.

type Run 

type Run struct {
	ID          int64
	Kind        string
	Status      string
	StartedAt   time.Time
	CompletedAt *time.Time
	Stats       string
	Error       string
}

Run records a crawl, hydration, indexing, or validation attempt.

type RunEvent 

type RunEvent struct {
	ID         int64
	RunID      int64
	Level      string
	Message    string
	RecordedAt time.Time
}

RunEvent is a durable log line emitted during a run.

type SchemaInspection added in v0.9.0 

type SchemaInspection struct {
	Path                      string
	Exists                    bool
	SizeBytes                 int64
	WALBytes                  int64
	State                     SchemaState
	Current                   int64
	Target                    int64
	Pending                   []MigrationStep
	Repository                int
	Threads                   int
	Problem                   string
	BackupRequired            bool
	RequiredDiskBytes         uint64
	AvailableDiskBytes        uint64
	ProjectionRebuildRequired bool
}

SchemaInspection is a read-only migration plan input.

func InspectSchema added in v0.9.0 

func InspectSchema(ctx context.Context, path string) (result SchemaInspection, returnErr error)

InspectSchema reports corpus identity, compatibility, and bounded inventory without creating or mutating the database.

type SchemaState added in v0.9.0 

type SchemaState string

SchemaState is the non-mutating compatibility classification for a corpus. 

const (
	// SchemaMissing indicates that no persistent corpus exists.
	SchemaMissing SchemaState = "missing"
	// SchemaCurrent indicates that the corpus matches the supported schema.
	SchemaCurrent SchemaState = "current"
	// SchemaMigrationRequired indicates that the corpus must be migrated.
	SchemaMigrationRequired SchemaState = "migration_required"
	// SchemaNewer indicates that the corpus is newer than this runtime supports.
	SchemaNewer SchemaState = "newer"
	// SchemaDamaged indicates that SQLite could not read the corpus safely.
	SchemaDamaged SchemaState = "damaged"
)

type SearchFilter 

type SearchFilter struct {
	RepoID       int64
	Repo         string
	Kind         string
	State        string
	StateReason  string
	Merged       *bool
	Author       string
	Association  string
	Assignee     string
	Labels       []string
	UpdatedAfter time.Time
	Limit        int
	Cursor       string
}

SearchFilter scopes a thread keyword search.

type SourcePartition 

type SourcePartition struct {
	SourceID     int64
	Key          string
	Query        string
	Qualifier    string
	Start        time.Time
	End          time.Time
	Total        int
	Pages        int
	Incomplete   bool
	Unsplittable bool
	Retries      int
	ObservedAt   time.Time
}

SourcePartition records one observed GitHub Search window.

type Status 

type Status struct {
	Repositories int
	Threads      int
}

Status holds corpus health and count metadata.

type Thread 

type Thread struct {
	ID                  int64
	RepositoryID        int64
	Kind                string
	Number              int
	State               string
	StateReason         string
	Title               string
	Body                string
	Author              string
	AuthorAssociation   string
	Labels              []string
	Assignees           []string
	Draft               bool
	Locked              bool
	Milestone           string
	ClosedAt            time.Time
	MergedAt            time.Time
	Merged              bool
	MergedKnown         bool
	SourceCreatedAt     time.Time
	SourceUpdatedAt     time.Time
	ObservationSequence int64
	CreatedAt           time.Time
	UpdatedAt           time.Time
	// Rank and match fields are query-specific and populated only by search results.
	Rank           float64
	MatchSource    string
	MatchExcerpt   string
	MatchUpdatedAt time.Time
}

Thread is the current projection of an issue or pull request.

type ThreadObservation 

type ThreadObservation struct {
	ID                  int64
	ThreadID            int64
	SourceUpdatedAt     time.Time
	ObservationSequence int64
	Payload             string
	ObservedAt          time.Time
}

ThreadObservation is an immutable snapshot received from a source.

type ThreadSearchEvidence added in v0.8.0 

type ThreadSearchEvidence struct {
	Source          string
	Text            string
	Excerpt         string
	SourceUpdatedAt time.Time
}

ThreadSearchEvidence is the stored document that made an exact thread match.

type ThreadSearchPage 

type ThreadSearchPage struct {
	Threads    []Thread
	NextCursor string
	Total      int
}

ThreadSearchPage is a paginated result of a thread keyword search.

type UnsupportedSchemaError added in v0.9.0 

type UnsupportedSchemaError struct {
	Current int64
	Target  int64
}

UnsupportedSchemaError reports that the corpus was written by a newer binary. Retaining an older executable is not sufficient for rollback once the durable schema has advanced.

func (*UnsupportedSchemaError) Error added in v0.9.0 

func (e *UnsupportedSchemaError) Error() string

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.