corpus

package
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 2026 License: MIT Imports: 46 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"
	ProjectionNameRepositoriesFTS      = "repositories_fts"
	ProjectionNameFacetObservationsFTS = "facet_observations_fts"
	ProjectionNameCodeDocumentsFTS     = "code_documents_fts"
)

Product-owned names for derived SQLite search projections.

View Source 
const (
	ProjectionVersionThreadsFTS           = "threads-fts-v3"
	ProjectionVersionRepositoriesFTS      = "repositories-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 RetryBusy added in v0.14.0 

func RetryBusy(ctx context.Context, fn func(context.Context) error) error

RetryBusy runs one idempotent local database operation and retries only SQLite busy results. The callback must not contain network or process work.

func RetryBusyValue added in v0.14.0 

func RetryBusyValue[T any](ctx context.Context, fn func(context.Context) (T, error)) (T, error)

RetryBusyValue is RetryBusy for an idempotent operation returning a value.

func SupportedSchemaLineage added in v0.12.0 

func SupportedSchemaLineage() string

SupportedSchemaLineage returns the durable identity required on every corpus supported by this binary.

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 ChangeWatch added in v0.11.0 

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

ChangeWatch detects commits made while a multi-read application snapshot is assembled. It owns a dedicated SQLite connection because data_version only changes for commits made by other connections.

func (*ChangeWatch) Close added in v0.11.0 

func (w *ChangeWatch) Close() error

Close releases the dedicated watcher connection.

func (*ChangeWatch) Unchanged added in v0.11.0 

func (w *ChangeWatch) Unchanged(ctx context.Context) (bool, error)

Unchanged reports whether no other connection committed after the watch began.

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 CodeSearchEvidence added in v0.10.0 

type CodeSearchEvidence struct {
	Rank    float64
	Excerpt string
}

CodeSearchEvidence is the ranked excerpt for one indexed file revision.

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
	Snapshots  []CodeSnapshotInfo
	NextCursor string
	Total      int
}

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

type CodeSnapshotInfo added in v0.10.0 

type CodeSnapshotInfo struct {
	Repo       domain.RepoRef
	RepoPath   string
	CommitSHA  string
	TotalBytes int
	CreatedAt  time.Time
	Manifest   codeindex.Manifest
}

CodeSnapshotInfo describes one stored code snapshot and its coverage.

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 CollectionList added in v0.11.0 

type CollectionList struct {
	Collections []Collection
	Total       int
	Truncated   bool
}

CollectionList is one bounded, stable page of named collections.

type CollectionMember 

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

CollectionMember is one typed stable reference in a collection.

type CollectionMemberList added in v0.11.0 

type CollectionMemberList struct {
	Members   []CollectionMember
	Total     int
	Truncated bool
}

CollectionMemberList is one bounded, stable page of collection members.

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 (c *Corpus) AddConcernLink(ctx context.Context, id string, link concern.Link) error

AddConcernLink idempotently stores one typed relationship.

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) BeginChangeWatch added in v0.11.0 

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

BeginChangeWatch captures the database revision on an independent read-only connection and keeps that connection alive until Close.

func (*Corpus) BindWorkspacePath added in v0.10.0 

func (c *Corpus) BindWorkspacePath(ctx context.Context, item *workspace.Workspace) (bound *workspace.Workspace, inserted bool, err error)

BindWorkspacePath atomically returns an existing exact path binding or inserts item. The immediate transaction prevents concurrent adopters from assigning the same external path to different workspace IDs.

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) CodeSnapshot added in v0.13.0 

func (c *Corpus) CodeSnapshot(ctx context.Context, ref domain.RepoRef, commit string) (*CodeSnapshotInfo, error)

CodeSnapshot returns the stored snapshot for an exact repository commit.

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. Cluster 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) CountRepositoryThreads added in v0.11.0 

func (c *Corpus) CountRepositoryThreads(ctx context.Context, repoID int64) (RepositoryThreadCounts, error)

CountRepositoryThreads returns complete repository thread counts.

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) FindCodeSearchEvidence added in v0.10.0 

func (c *Corpus) FindCodeSearchEvidence(ctx context.Context, docID int64, query string) (CodeSearchEvidence, bool, error)

FindCodeSearchEvidence returns the weighted FTS5 rank and matching excerpt for one exact indexed document.

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) FindRepositorySearchEvidence added in v0.10.0 

func (c *Corpus) FindRepositorySearchEvidence(ctx context.Context, id int64, query string) (RepositorySearchEvidence, bool, error)

FindRepositorySearchEvidence returns the weighted FTS5 rank and matching repository metadata excerpt.

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) GetClusterProjectionForMemberWithIdentity added in v0.10.0 

func (c *Corpus) GetClusterProjectionForMemberWithIdentity(ctx context.Context, ref clustering.MemberRef) (result clusterprojection.List, err error)

GetClusterProjectionForMemberWithIdentity reads the current included cluster containing ref together with the projection identity that produced it.

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) GetConcern added in v0.10.0 

func (c *Corpus) GetConcern(ctx context.Context, id string) (*concern.Concern, error)

GetConcern returns one local concern with its explicit links.

func (*Corpus) GetContribution 

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

GetContribution returns a contribution by durable id.

func (*Corpus) GetContributionDraftRevision added in v0.14.0 

func (c *Corpus) GetContributionDraftRevision(ctx context.Context, draftID string, revision int) (*contribution.DraftArtifact, error)

GetContributionDraftRevision returns one immutable stored draft revision.

func (*Corpus) GetContributionManifest added in v0.10.0 

func (c *Corpus) GetContributionManifest(ctx context.Context, id string) (*manifest.Statement, error)

GetContributionManifest reads one persisted evidence statement.

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) GetJobsBatch added in v0.13.0 

func (c *Corpus) GetJobsBatch(ctx context.Context, ids []string, includePayload bool) (map[string]*Job, error)

GetJobsBatch returns jobs keyed by ID in one query. When includePayload is false, request and result blobs are not loaded from SQLite.

func (*Corpus) GetLatestDossierMetadataBatch added in v0.13.0 

func (c *Corpus) GetLatestDossierMetadataBatch(ctx context.Context, repositoryIDs []int64) (map[int64]DossierMetadata, error)

GetLatestDossierMetadataBatch returns the latest persisted dossier metadata for each requested repository ID without loading dossier snapshots.

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) GetRepositoriesBatch added in v0.13.0 

func (c *Corpus) GetRepositoriesBatch(ctx context.Context, keys []RepositoryKey) (map[RepositoryKey]*Repository, error)

GetRepositoriesBatch reads up to 100 repository projections in one query. Missing repositories are absent from the returned map.

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) GetThreadsBatch added in v0.13.0 

func (c *Corpus) GetThreadsBatch(ctx context.Context, keys []ThreadKey) (map[ThreadKey]*Thread, error)

GetThreadsBatch reads up to 100 exact thread projections in one query. Missing threads are absent from the returned map.

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) GetValidationRunGroup added in v0.10.0 

func (c *Corpus) GetValidationRunGroup(ctx context.Context, id string) (*evidence.ValidationRunGroup, error)

GetValidationRunGroup returns one persisted repeat/stress aggregate.

func (*Corpus) GetWorkspace 

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

GetWorkspace returns a workspace by ID.

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) (*CodeSnapshotInfo, error)

LatestCodeSnapshot returns the latest source snapshot selected for a repository, or nil if none exists.

func (*Corpus) LatestContributionManifest added in v0.10.0 

func (c *Corpus) LatestContributionManifest(ctx context.Context, opportunityID string) (*manifest.Statement, error)

LatestContributionManifest reads the newest manifest for an opportunity.

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) (CollectionMemberList, error)

ListCollectionMembers returns a bounded member page in stable kind and reference order.

func (*Corpus) ListCollections 

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

ListCollections returns a bounded collection page in stable name order.

func (*Corpus) ListConcerns added in v0.10.0 

func (c *Corpus) ListConcerns(ctx context.Context, filter concern.Filter) (_ *concern.ListResult, err error)

ListConcerns performs a bounded offline FTS5 search or updated-order list.

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) (DiscoverySourceList, error)

ListDiscoverySources returns a bounded source page 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) (LensList, error)

ListLenses returns a bounded lens page 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) ListPullRequestPortfolioPage added in v0.10.0 

func (c *Corpus) ListPullRequestPortfolioPage(ctx context.Context, author, state string, limit int) (_ PortfolioPage, err error)

ListPullRequestPortfolioPage returns a bounded portfolio and the exact matching population so callers never mistake the page size for the total.

func (*Corpus) ListRecentClusters added in v0.11.0 

func (c *Corpus) ListRecentClusters(ctx context.Context, limit int) (_ []clustering.Cluster, total int, err error)

ListRecentClusters returns the globally newest non-retired clusters from one read snapshot. It avoids repository-order bias in bounded browse surfaces.

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, err error)

ListRepositoriesWithOptions returns repositories matching weighted owner, name, topic, and description text with stable cursor pagination. Relevance is the default; updated order is explicit. Both orders use deterministic tie-breakers on an unchanged corpus.

func (*Corpus) ListRepositoryCoverageBatch added in v0.13.0 

func (c *Corpus) ListRepositoryCoverageBatch(ctx context.Context, repositoryIDs []int64, facets []string) (map[RepositoryFacetKey]*Coverage, error)

ListRepositoryCoverageBatch returns repository-scoped coverage for a bounded set of repository facets in one query. Missing keys are absent.

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) ListThreadCoverageBatch added in v0.13.0 

func (c *Corpus) ListThreadCoverageBatch(ctx context.Context, threadIDs []int64, facets []string) (map[ThreadFacetKey]*Coverage, error)

ListThreadCoverageBatch returns stored coverage for a bounded set of thread facets in one query. Missing keys are intentionally absent from the result.

func (*Corpus) ListThreadFacetObservationsBatch added in v0.13.0 

func (c *Corpus) ListThreadFacetObservationsBatch(ctx context.Context, threadIDs []int64, facets []string, limit int) (map[ThreadFacetKey]FacetObservationBatch, error)

ListThreadFacetObservationsBatch returns up to limit observations per thread-facet key in one query while preserving observation order.

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) ListThreadsByStateAndMerge added in v0.11.0 

func (c *Corpus) ListThreadsByStateAndMerge(ctx context.Context, repoID int64, kind, state string, merged *bool, limit int) (_ []Thread, returnErr error)

ListThreadsByStateAndMerge returns every matching thread when limit is non-positive. Positive limits apply after all predicates.

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) PromoteConcern added in v0.10.0 

func (c *Corpus) PromoteConcern(ctx context.Context, id string, inv *investigation.Investigation, hypothesis *investigation.Hypothesis, opportunity *investigation.Opportunity) (_ *concern.Concern, err error)

PromoteConcern atomically creates the downstream workflow and marks the concern promoted. A nil opportunity promotes only to an investigation.

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) RebuildRepositorySearchProjection added in v0.10.0 

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

RebuildRepositorySearchProjection atomically rebuilds repository search.

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) SaveConcern added in v0.10.0 

func (c *Corpus) SaveConcern(ctx context.Context, item *concern.Concern) error

SaveConcern stores one validated concern and updates its FTS document through database triggers.

func (*Corpus) SaveContribution 

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

SaveContribution stores contribution metadata separate from GitHub state.

func (*Corpus) SaveContributionManifest added in v0.10.0 

func (c *Corpus) SaveContributionManifest(ctx context.Context, item *manifest.Statement, workspaceID, pullRequestRef string) error

SaveContributionManifest persists one deterministic evidence statement.

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) SaveValidationRunGroup added in v0.10.0 

func (c *Corpus) SaveValidationRunGroup(ctx context.Context, item *evidence.ValidationRunGroup) error

SaveValidationRunGroup persists one bounded repeat/stress aggregate.

func (*Corpus) SaveWorkspace 

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

SaveWorkspace inserts or replaces a 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, err error)

SearchCodeWithOptions searches only the latest indexed snapshot of each repository with stable cursor pagination. It returns bounded FTS snippets, not complete files. Results are ordered by weighted 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) StoppedJobIDs added in v0.13.0 

func (c *Corpus) StoppedJobIDs(ctx context.Context, ids []string) (_ map[string]struct{}, err error)

StoppedJobIDs returns job IDs with a persisted cancellation request or no durable row. Workers must stop in either case.

func (*Corpus) StoreCodeSnapshot 

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

StoreCodeSnapshot atomically stores one complete code snapshot. Replaying the same repository commit replaces its documents and coverage metadata without changing its ordering relative to other commits.

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) UpdateConcern added in v0.11.0 

func (c *Corpus) UpdateConcern(ctx context.Context, previous, next *concern.Concern) error

UpdateConcern replaces exactly the revision returned to the caller. Links live in concern_links and are excluded from the payload comparison.

func (*Corpus) UpdateHypothesis added in v0.11.0 

func (c *Corpus) UpdateHypothesis(ctx context.Context, previous, next *investigation.Hypothesis) error

UpdateHypothesis conditionally replaces the exact revision read by the caller, preserving concurrent status and audit updates.

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) UpdateOpportunity added in v0.11.0 

func (c *Corpus) UpdateOpportunity(ctx context.Context, previous, next *investigation.Opportunity, blockContradicting bool) error

UpdateOpportunity conditionally replaces the exact revision read by the caller. For advancing transitions, the same SQL statement also rejects any contradicting evidence visible when the status write is serialized.

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 DiscoverySourceList added in v0.11.0 

type DiscoverySourceList struct {
	Sources   []DiscoverySource
	Total     int
	Truncated bool
}

DiscoverySourceList is one bounded, stable page of discovery sources.

type DossierMetadata added in v0.13.0 

type DossierMetadata struct {
	RepositoryID int64
	AsOf         time.Time
	GeneratedAt  time.Time
}

DossierMetadata is the small latest-snapshot projection needed by bounded repository reads.

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 FacetObservationBatch added in v0.13.0 

type FacetObservationBatch struct {
	Observations []FacetObservation
	HasMore      bool
}

FacetObservationBatch is one bounded thread-facet observation sequence.

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 IncompatibleSchemaError added in v0.12.0 

type IncompatibleSchemaError struct {
	Current int64
	Target  int64
}

IncompatibleSchemaError reports that a database does not carry this product's durable schema identity. The database remains untouched.

func (*IncompatibleSchemaError) Error added in v0.12.0 

func (e *IncompatibleSchemaError) Error() string

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 LensList added in v0.11.0 

type LensList struct {
	Records   []LensRecord
	Total     int
	Truncated bool
}

LensList is one bounded, stable page of saved lenses.

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 PortfolioPage added in v0.10.0 

type PortfolioPage struct {
	PullRequests []PortfolioPullRequest
	Total        int
	Truncated    bool
}

PortfolioPage reports the complete matching population separately from the bounded returned items.

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
	// Rank is query-specific and populated only by full-text search results.
	Rank float64
}

Repository is the current projection of a GitHub repository.

type RepositoryFacetKey added in v0.13.0 

type RepositoryFacetKey struct {
	RepositoryID int64
	Facet        string
}

RepositoryFacetKey identifies one repository-scoped hydration facet.

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 RepositoryKey added in v0.13.0 

type RepositoryKey struct {
	Owner string
	Name  string
}

RepositoryKey identifies a repository projection in a batch result.

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 RepositorySearchEvidence added in v0.10.0 

type RepositorySearchEvidence struct {
	Rank    float64
	Excerpt string
}

RepositorySearchEvidence is the ranked excerpt for one repository match.

type RepositorySearchOptions 

type RepositorySearchOptions struct {
	Limit  int
	Cursor string
	Sort   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 RepositoryThreadCounts added in v0.11.0 

type RepositoryThreadCounts struct {
	OpenIssues            int
	ClosedIssues          int
	OpenPullRequests      int
	MergedPullRequests    int
	ClosedUnmergedPRs     int
	ClosedUnknownMergePRs int
}

RepositoryThreadCounts summarizes every stored issue and pull request for a repository without materializing thread bodies.

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 belongs to the canonical lineage
	// but requires a newer runtime.
	SchemaNewer SchemaState = "newer"
	// SchemaIncompatible indicates that the corpus belongs to an unsupported
	// schema lineage. Inspection never mutates it.
	SchemaIncompatible SchemaState = "incompatible"
	// 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
	UpdatedBefore time.Time
	Limit         int
	Cursor        string
	Sort          string
	MatchMode     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
	MatchTruncated bool
}

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

type ThreadFacetKey added in v0.13.0 

type ThreadFacetKey struct {
	ThreadID int64
	Facet    string
}

ThreadFacetKey identifies one thread-scoped hydration facet.

type ThreadKey added in v0.13.0 

type ThreadKey struct {
	RepositoryID int64
	Kind         string
	Number       int
}

ThreadKey identifies a thread projection in a batch result. An empty Kind requests the thread regardless of whether it is 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
	Rank            float64
	Truncated       bool
}

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

type ThreadSearchPage 

type ThreadSearchPage struct {
	Threads           []Thread
	NextCursor        string
	Total             int
	UnknownMergeCount 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 belongs to this product lineage but requires a newer binary.

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.