scope

type AcceptOptions struct {
	// Force accepts despite self-check conflicts.
	Force bool
	// Yes activates without the interactive confirmation (scripts).
	Yes bool
	// Confirm asks the user to type the topic slug; it returns the typed
	// text. Nil without Yes means the draft is never activated.
	Confirm func(prompt string) (string, error)
	// Preview configures the impact preview.
	Preview PreviewOptions
	// OnSelfCheck and OnPreview, when set, receive each step's outcome as
	// soon as it is known (before the confirmation prompt).
	OnSelfCheck func(Conflicts)
	OnPreview   func(PreviewReport)
}

type AcceptReport struct {
	Draft     *contract.Contract `json:"draft"`
	SelfCheck Conflicts          `json:"self_check"`
	// Forced reports conflicts accepted through Force.
	Forced bool `json:"forced,omitempty"`
	// Preview is nil when the self-check blocked.
	Preview   *PreviewReport `json:"preview,omitempty"`
	Activated bool           `json:"activated"`
}

type BandCounts struct {
	Kept       int `json:"kept"`
	Review     int `json:"review"`
	Quarantine int `json:"quarantine"`
	Undecided  int `json:"undecided"`
}

type Conflict struct {
	Pair
	P float64 `json:"p"`
}

type Conflicts struct {
	Pairs     int        `json:"pairs"`
	Threshold float64    `json:"threshold"`
	Conflicts []Conflict `json:"conflicts"`
	// Undecided lists pairs without a usable answer ("conflict_<n>:<reason>").
	Undecided []string `json:"undecided,omitempty"`
}

type DecisionSummary struct {
	Decision string        `json:"decision"`
	Count    int           `json:"count"`
	Reasons  []ReasonCount `json:"reasons,omitempty"`
	Examples []string      `json:"examples,omitempty"`
}

type DraftInputs struct {
	Title  string `json:"title"`
	Domain string `json:"domain"`
	// ScopeText is the `Topic scope` line of CLAUDE.md, when set.
	ScopeText string `json:"scope_text,omitempty"`
	// ExistingContract is the parsed `## Selection contract` section of
	// CLAUDE.md, when it carries text.
	ExistingContract *contract.Contract `json:"existing_contract,omitempty"`
	Articles         []string           `json:"articles"`
	// Sources is the total number of sources; SourceSample holds the
	// stratified sample of their titles.
	Sources      int                `json:"sources"`
	SourceSample []SampleSource     `json:"source_sample"`
	Folders      []FolderCount      `json:"folders"`
	Screening    []ScreeningSummary `json:"screening,omitempty"`
	// Dropped lists what code validation removed from the generated draft
	// (duplicate lines, invalid globs, out_of_scope lines equal to a kept
	// line).
	Dropped []string `json:"dropped,omitempty"`
}

type DraftOptions struct {
	// SourceSample is the number of source titles in the prompt (default 60).
	SourceSample int
	// ScreeningReasons caps the distinct reasons per screening decision
	// (default 8).
	ScreeningReasons int
	// Exclude are topic.yaml `decisions.exclude` globs: matching files
	// (CLAUDE.md, screening files; the corpus already drops documents) never
	// enter the draft prompt (spec §14). Draft sets it from the session.
	Exclude []string
}

type FolderBands struct {
	Folder string `json:"folder"`
	Judged int    `json:"judged"`
	BandCounts
}

type FolderCount struct {
	Folder string `json:"folder"`
	Files  int    `json:"files"`
}

type LabelScore struct {
	// Labels counts the labeled subjects that were judged with a decided
	// role; Negatives counts the negative ones among them.
	Labels    int `json:"labels"`
	Negatives int `json:"negatives"`
	// Predicted counts labeled subjects at P(off_topic) ≥ relevance_quarantine.
	Predicted    int     `json:"predicted"`
	TruePositive int     `json:"true_positive"`
	Precision    float64 `json:"precision"`
	Recall       float64 `json:"recall"`
}

type Pair struct {
	// N numbers the pair from 1; the question id is `conflict_<N>`.
	N int `json:"n"`
	// KeptField is "core" or "adjacent".
	KeptField string `json:"kept_field"`
	Kept      string `json:"kept"`
	Excluded  string `json:"excluded"`
}

type PreviewOptions struct {
	// SampleSize caps the judged sources (default 500); larger topics are
	// sampled with Stratify.
	SampleSize int
	// TopN is the length of the highest-P(off_topic) list (default 20).
	TopN int
	// OnEstimate, when set, is called with the planned judgments and their
	// estimated cost before any call is made.
	OnEstimate func(documents int, estimateUSD float64)
}

type PreviewReport struct {
	// Contract is the hash of the previewed draft.
	Contract string `json:"contract"`
	// Sources is the topic's source count; Judged the documents judged.
	Sources int  `json:"sources"`
	Judged  int  `json:"judged"`
	Sampled bool `json:"sampled"`
	// RelevanceOff reports topic.yaml decisions.relevance: off (quality only).
	RelevanceOff bool               `json:"relevance_off,omitempty"`
	Thresholds   map[string]float64 `json:"thresholds"`
	Bands        BandCounts         `json:"bands"`
	Folders      []FolderBands      `json:"folders"`
	Top          []TopDocument      `json:"top"`
	Labels       *LabelScore        `json:"labels,omitempty"`
	Undecided    map[string]int     `json:"undecided_reasons,omitempty"`
	EstimateUSD  float64            `json:"estimate_usd"`
	CostUSD      float64            `json:"cost_usd"`
	// contains filtered or unexported fields
}

type ReasonCount struct {
	Reason string `json:"reason"`
	Count  int    `json:"count"`
}

type SampleSource struct {
	Title  string `json:"title"`
	Folder string `json:"folder"`
}

type ScreeningSummary struct {
	File      string            `json:"file"`
	Rows      int               `json:"rows"`
	Decisions []DecisionSummary `json:"decisions"`
}

type TopDocument struct {
	Path      string  `json:"path"`
	Title     string  `json:"title"`
	POffTopic float64 `json:"p_off_topic"`
	Band      string  `json:"band"`
	// Reason is the quality reason when quality drove the band.
	Reason string `json:"reason,omitempty"`
}