corpus

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 18, 2026 License: MIT Imports: 28 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.

Variables

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 ErrThreadObservationRevisionNotFound = errors.New("thread observation revision not found")

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

Functions

This section is empty.

Types

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 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 an FTS5 thread index.

func Open 

func Open(ctx context.Context, path string) (*Corpus, 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 (*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) 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) 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) 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 bounded, local database health checks and verifies that an immediate write lock can be acquired. It does not mutate user data.

func (*Corpus) Close 

func (c *Corpus) Close() error

Close closes the underlying database connection.

func (*Corpus) Clustering 

func (c *Corpus) Clustering() *clustering.Store

Clustering returns the duplicate-candidate clustering store backed by this corpus. The corpus schema includes the clustering tables, so this store is ready for use after Open.

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) 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) 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) 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) 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) 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) 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) 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) 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 (*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) MarkImported 

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

MarkImported records an imported GH Archive hour idempotently.

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) 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) 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) 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 (*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) 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) 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 titles and bodies. 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
}

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 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 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 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 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 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 SearchFilter 

type SearchFilter struct {
	RepoID       int64
	Repo         string
	Kind         string
	State        string
	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
	SourceCreatedAt     time.Time
	SourceUpdatedAt     time.Time
	ObservationSequence int64
	CreatedAt           time.Time
	UpdatedAt           time.Time
	// Rank is the query-specific FTS rank populated only by search results.
	Rank float64
}

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 ThreadSearchPage 

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

ThreadSearchPage is a paginated result of a thread keyword search.

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.