Documentation
¶
Overview ¶
Package clustering computes exact duplicate-thread clusters from caller-owned candidate snapshots.
Computation is deterministic, cancellable, bounded by an ExactPairBudget, and free of storage and network side effects. Durable projection lifecycle, governance, and stale-safe atomic persistence belong to the corpus and clusterprojection packages.
Index ¶
- Constants
- func SourceRevision(candidates []Candidate) string
- func SourceWindow(candidates []Candidate) (time.Time, time.Time)
- type Candidate
- type CapacityError
- type Cluster
- type ClusterState
- type Computation
- type Engine
- type ExactPairBudget
- type Member
- type MemberRef
- type MembershipOverride
- type Neighbor
- type OverrideAction
Constants ¶
const ( DefaultNeighborsLimit = 10 MaxNeighborsLimit = 1000 )
Neighbor defaults and hard limits.
Variables ¶
This section is empty.
Functions ¶
func SourceRevision ¶
SourceRevision returns a full SHA-256 digest of every candidate field that can affect duplicate scoring or the stored projection. Candidate and label ordering do not affect the digest.
Types ¶
type Candidate ¶
type Candidate struct {
ThreadID int64
Repo domain.RepoRef
Kind string
Number int
State string
Title string
Body string
Author string
Labels []string
CreatedAt time.Time
UpdatedAt time.Time
}
Candidate is a thread considered for duplicate-candidate clustering.
type CapacityError ¶ added in v0.8.0
CapacityError reports candidate work that cannot execute within an exact pair budget.
func (*CapacityError) Error ¶ added in v0.8.0
func (e *CapacityError) Error() string
Error describes the rejected exact-work request.
type Cluster ¶
type Cluster struct {
ID int64
StableID string
State ClusterState
Repo domain.RepoRef
Canonical MemberRef
Revision string
WindowStart time.Time
WindowEnd time.Time
Members []Member
CreatedAt time.Time
UpdatedAt time.Time
}
Cluster is a group of duplicate-candidate threads.
func ReconcileProjection ¶ added in v0.8.0
func ReconcileProjection( ctx context.Context, raw []Cluster, existing []Cluster, overridesByStable map[string][]MembershipOverride, candidates []Candidate, repo domain.RepoRef, revision string, now time.Time, ) ([]Cluster, error)
ReconcileProjection applies durable governance and projection metadata to a pure engine computation. All existing clusters, members, overrides, and candidates must come from the same storage snapshot. StableID remains tied to the engine-selected canonical member even when governance changes the displayed canonical member, so later refreshes can find the same history.
type ClusterState ¶
type ClusterState string
ClusterState is the local lifecycle of a cluster.
const ( ClusterOpen ClusterState = "open" ClusterClosed ClusterState = "closed" // ClusterRetired preserves governance history for a cluster that is no // longer present in the latest computation. ClusterRetired ClusterState = "retired" )
type Computation ¶ added in v0.8.0
type Computation struct {
Clusters []Cluster
CandidateCount int
RequiredPairs uint64
ComparedPairs uint64
RuleVersion similarity.RuleVersion
}
Computation describes one complete exact clustering result.
type Engine ¶ added in v0.8.0
type Engine struct {
// contains filtered or unexported fields
}
Engine performs bounded, cancellable exact duplicate clustering.
func NewEngine ¶ added in v0.8.0
func NewEngine(rule similarity.DuplicateRule, budget ExactPairBudget) (Engine, error)
NewEngine constructs an exact clustering engine from a valid rule and nonzero budget.
func (Engine) Cluster ¶ added in v0.8.0
Cluster computes exact duplicate clusters without storage side effects.
func (Engine) MaxCandidates ¶ added in v0.8.0
MaxCandidates returns the population bound derived from the exact pair budget.
func (Engine) RuleVersion ¶ added in v0.8.0
func (e Engine) RuleVersion() similarity.RuleVersion
RuleVersion identifies the exact scoring rule used by the engine.
type ExactPairBudget ¶ added in v0.8.0
type ExactPairBudget uint64
ExactPairBudget bounds the number of exact candidate comparisons in one clustering run.
func DefaultExactPairBudget ¶ added in v0.8.0
func DefaultExactPairBudget() ExactPairBudget
DefaultExactPairBudget returns the repository's supported exact-work budget.
func (ExactPairBudget) MaxCandidates ¶ added in v0.8.0
func (b ExactPairBudget) MaxCandidates() int
MaxCandidates returns the greatest population whose all-pairs work fits the budget.
type Member ¶
type Member struct {
ThreadID int64
Ref MemberRef
Title string
State string
Score float64
Reason string
Included bool
}
Member is one thread inside a cluster.
type MemberRef ¶
MemberRef identifies a thread across repositories and kinds.
func ExtractMemberRefs ¶ added in v0.8.0
ExtractMemberRefs adapts exact GitHub references to cluster member values.
type MembershipOverride ¶
type MembershipOverride struct {
ID int64
ClusterID int64
Ref MemberRef
Action OverrideAction
Reason string
CreatedAt time.Time
}
MembershipOverride records an explicit local include/exclude/canonical decision.
type Neighbor ¶
type Neighbor struct {
ThreadID int64
Ref MemberRef
Title string
State string
Score float64
Reason string
}
Neighbor is a scored thread near a query candidate.
func Neighbors ¶
func Neighbors(ctx context.Context, query Candidate, candidates []Candidate, limit int) ([]Neighbor, error)
Neighbors scores every candidate against the query using deterministic local signals and returns the top limit results with stable tie ordering.
The query itself is excluded from the returned set. Scores and reasons are produced by the same versioned duplicate rule used for clustering.
type OverrideAction ¶
type OverrideAction string
OverrideAction is a local governance instruction for a cluster member.
const ( OverrideInclude OverrideAction = "include" OverrideExclude OverrideAction = "exclude" OverrideSetCanonical OverrideAction = "set_canonical" )
Source Files