Documentation
¶
Overview ¶
Package convergence derives review-loop convergence telemetry from a step's persisted execution rounds, and decides when the loop is measurably not converging (the "ladder" failure mode: fix rounds that relocate or grow the finding set instead of shrinking it).
The package is pure: it reads already-persisted db.StepRound rows plus the originally submitted changed-file list and produces a Report. The executor evaluates and persists the report once per review round; status surfaces only render what was persisted, so there is exactly one evaluation owner and no threshold drift between the daemon and the CLI.
The guard is advisory by design: a tripped report never aborts a run. It stops the pipeline from spending further automatic fix rounds and parks the gate for an explicit decision, with the full history attached, and the operator can still respond fix deliberately.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatRoundCounts ¶
FormatRoundCounts renders per-round findings counts as "1,1,1,2,3,3,3".
Types ¶
type RecurringClass ¶
type RecurringClass struct {
Label string `json:"label"`
Rounds []int `json:"rounds"`
Files []string `json:"files,omitempty"`
}
RecurringClass is one finding class observed in multiple distinct rounds.
type Report ¶
type Report struct {
// RoundFindings is the findings count of every review round so far, in
// round order (e.g. 1,1,1,2,3,3,3 for the observed ladder).
RoundFindings []int `json:"round_findings"`
// ReviewMS is the cumulative review execution wall clock across all
// rounds, excluding time parked at gates.
ReviewMS int64 `json:"review_ms"`
// NewSurfaceFindings counts findings (across all rounds) whose file did
// not appear in the originally submitted diff: surface the fix rounds
// created rather than repaired. Nil when the submitted file list could
// not be determined; never a fabricated zero.
NewSurfaceFindings *int `json:"new_surface_findings,omitempty"`
// Recurring lists finding classes seen in two or more distinct rounds,
// keyed by content rather than by file path or generated id, so a defect
// that moves files between rounds is visible as the same defect.
Recurring []RecurringClass `json:"recurring,omitempty"`
// Warning is non-empty exactly when the guard tripped. It names every
// trigger that fired.
Warning string `json:"warning,omitempty"`
}
Report is the per-review-step convergence report persisted as JSON on step_results.convergence_json and rendered at the gate.
func BuildReport ¶
func BuildReport(rounds []*db.StepRound, submittedFiles []string, submittedKnown bool, t Thresholds) Report
BuildReport computes the convergence telemetry for a review step's rounds and evaluates the guard against the given thresholds. submittedKnown is false when the originally submitted changed-file list could not be determined; the new-surface count is then omitted rather than fabricated.
func ParseReport ¶
ParseReport decodes a persisted report. It fails soft: any input that does not decode to a report with content simply reports absence.
type Thresholds ¶
type Thresholds struct {
// NonDecreasingRounds trips the guard when the findings count has not
// decreased across this many trailing consecutive rounds (all non-zero).
NonDecreasingRounds int
// RecurringRounds trips the guard when one finding class recurs in this
// many distinct rounds.
RecurringRounds int
// BudgetMS trips the guard when cumulative review execution time reaches
// this budget.
BudgetMS int64
}
Thresholds configure the guard. A zero value disables that trigger, so the zero Thresholds is a fully disabled guard that still produces telemetry.
Source Files