curate

type Agent struct {
	Passes []Pass
	Log    *slog.Logger
}

type ClosedPRLister interface {
	ListClosedUnmergedPRsByLabel(ctx context.Context, label string) ([]providers.CuratedIssue, error)
}

type ClosedPRSuppression struct {
	Forge ClosedPRLister
}

type Contested struct {
	Forge  ContestedForge
	Ledger ContestedSource
	KBRepo string // configured forge.kb_repo ("owner/name"); KB links outside it are foreign and skipped
	Log    *slog.Logger
}

type ContestedForge interface {
	Comment(ctx context.Context, number int, body string) error
	ListIssueCommentBodies(ctx context.Context, number int) ([]string, error)
	IsPROpen(ctx context.Context, number int) (bool, error)
}

type ContestedSource interface {
	ContestedTriggers() []outcome.ContestedTrigger
}

type Dedup struct {
	Forge     Forge
	Threshold float64 // title-Jaccard fallback threshold for markerless PRs; default 0.6 when 0
	Log       *slog.Logger
}

type Forge interface {
	ListPRsByLabel(ctx context.Context, label string) ([]providers.CuratedIssue, error)
	ListIssuesByLabel(ctx context.Context, label string) ([]providers.CuratedIssue, error)
	Comment(ctx context.Context, number int, body string) error
	ReplaceLabel(ctx context.Context, number int, remove, add string) error
	Close(ctx context.Context, number int) error
	OpenIssue(ctx context.Context, inv providers.Investigation) (providers.Ref, error)
}

type Guard struct {
	Inner  GuardedForge
	DryRun bool
	Audit  audit.Auditor // nil-safe: nil drops records (actions are still slog-logged)
	Log    *slog.Logger
}

type GuardedForge interface {
	Forge
	RetireForge
	ContestedForge
}

type LedgerResolutionChecker struct {
	Ledger interface {
		Episodes() ([]outcome.Episode, error)
	}
}

type Lifecycle struct {
	Forge      Forge
	StaleAfter time.Duration    // 0 disables the sweep
	Now        func() time.Time // injectable clock; nil ⇒ time.Now
	Log        *slog.Logger
}

type Pass interface {
	Run(ctx context.Context) error
}

type Queue struct {
	Forge   Forge
	Checker ResolutionChecker
	Log     *slog.Logger
}

type Recurrence struct {
	Forge  Forge
	Ledger interface {
		Episodes() ([]outcome.Episode, error)
	}
	Threshold int // default 3 when 0
	// Suppressed, when set, is the set of KB entries a human closed WITHOUT merging
	// (keyed by DupFingerprint). Their episodes are counted SEPARATELY — silently,
	// keyed on the fingerprint — and, past the threshold, escalate via a knowledge-gap
	// issue that LINKS the closed PR ("closed unmerged but recurred N times —
	// reconsider?") instead of the plain gap message. A close-without-merge is a
	// deliberate "no": we respect it and never reopen the PR. Nil disables the branch
	// (behaviour is then identical to the pre-suppression pass).
	Suppressed SuppressionSource
	Log        *slog.Logger
}

type ResolutionChecker interface {
	IsResolved(ctx context.Context, pr providers.CuratedIssue) (bool, error)
}

type RetireForge interface {
	ListPRsByLabel(ctx context.Context, label string) ([]providers.CuratedIssue, error)
	ListClosedUnmergedPRsByLabel(ctx context.Context, label string) ([]providers.CuratedIssue, error)
	OpenRetirePR(ctx context.Context, entryPath, body string) (providers.Ref, error)
}

type RetireStats interface {
	OpenCounts() (map[string]outcome.Aggregate, error)
}

type Retirement struct {
	Forge           RetireForge
	Stats           RetireStats
	MinObservations int     // sustained-decay bar: total observations before retirement is considered
	Floor           float64 // retire when Factor(Prior) < Floor
	Prior           float64 // k — must equal recall's outcome_prior so both gates agree
	Log             *slog.Logger
}

type Suppress struct {
	Forge  Forge
	Source SuppressionSource
	Log    *slog.Logger
}

type SuppressedEntry struct {
	Fingerprint string // curator DupFingerprint (resource+cause); the join key against ledger episodes
	PRNumber    int    // the closed-unmerged KB PR to reference in the escalation
	Reason      string // the close-reason label, when one distinguishes it (e.g. "wontfix"); "" otherwise
}

type SuppressionSource interface {
	Suppressed(ctx context.Context) (map[string]SuppressedEntry, error)
}

type Sweeper struct {
	Agent    Agent
	Interval time.Duration // <= 0 ⇒ DefaultSweepInterval
	Log      *slog.Logger
}