distill

type Config struct {
	Distill struct {
		// Write lets `lessons --apply` edit .seamark/lessons.yaml. Off
		// by default: without it, apply prints the pin block for manual
		// insertion. Seamark edits a reviewed config only when that same
		// config opts in.
		Write bool `yaml:"write"`
	} `yaml:"distill"`
}

type ExtractOptions struct {
	// Root is the workspace root; named paths are verified against it.
	Root string
	// DryRun stops after the preflight: nothing is sent.
	DryRun bool
	// Agent is the resolved agent command line, for disclosure only.
	Agent []string
	// OnPreflight receives the plan before the first call — always,
	// so sending note text to a model-backed CLI is never a surprise.
	OnPreflight func(ExtractPreflight)
	// OnBatchStart/OnBatchDone drive interactive surfaces through the
	// long silent stretch of each agent call — the same contract as
	// distill's group callbacks. When nil, the same information flows
	// through Logf as plain lines.
	OnBatchStart func(desc string)
	OnBatchDone  func(outcome string)
	// Logf receives progress; nil discards it.
	Logf func(format string, args ...any)
}

type ExtractPreflight struct {
	Proposals   int
	Batches     int
	PromptChars int
	Agent       []string
	BodyCap     int
}

type ExtractResult struct {
	Examined   int // proposals sent to the agent
	Named      int // proposals whose reply named at least one path
	Stored     int // proposals with at least one validated path stored
	Retargeted int // pending rows whose regions changed
	// AppliedStored counts applied pins that stored new triggers —
	// the rows whose drift the user must apply with --retarget. An
	// explicit counter: inferring it from Stored minus Retargeted
	// miscounts pending rows whose regions did not change.
	AppliedStored int
	BatchesFailed int // batches lost to agent or parse errors (retryable)
	PromptChars   int
	ReplyChars    int
	Duration      time.Duration
}

type FindingPlan struct {
	ID     int64
	Source string
	PR     int
	Path   string
	Paths  []string
}

type Group struct {
	// Region is the deepest directory common to every member, "" when
	// the members span top-level trees (a repo-wide theme batch).
	Region string
	// Findings are the members, ordered by id.
	Findings []model.Finding
	// Signature identifies the evidence set: the hash of the member
	// ids. Same members — same signature, regardless of ordering or of
	// anything outside the group.
	Signature string
	// Area marks a directory bucket: thematically unconnected findings
	// batched so distillation still covers them. Membership in an area
	// group only means "same directory", so consumers that treat group
	// membership as "same mistake" (the outcome loop) must skip these.
	Area bool
}

type GroupPlan struct {
	Signature   string
	Region      string
	Findings    int
	PromptChars int
	BodyCap     int
	Evidence    []FindingPlan
}

type Grouper interface {
	Group(findings []model.Finding) []Group
}

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

type Options struct {
	// Region restricts the finding corpus before grouping ("" =
	// everywhere). This keeps unrelated findings outside a requested tree
	// from changing token frequencies, bridging components, or consuming a
	// budgeted call.
	Region string
	// Limit caps how many new groups one run reads (0 = all). The cap
	// is the budget lever: each group is one agent invocation.
	Limit int
	// Logf receives progress; nil discards it.
	Logf func(format string, args ...any)
	// OnGroupStart/OnGroupDone drive interactive surfaces through the
	// long silent stretch of each agent call: start fires with the
	// group's description before the call, done with the outcome after.
	// When nil, the same information flows through Logf as plain lines.
	OnGroupStart func(desc string)
	OnGroupDone  func(outcome string)
	// Pins are the patterns already captured in .seamark/lessons.yaml,
	// hand-written ones included, as Rule/Note pairs. A distilled
	// pattern that restates one of them is dropped: groups are read
	// independently, so a repo-wide mistake would otherwise be
	// re-proposed under a new name by every group it appears in.
	Pins []model.Proposal
	// Agent is the resolved agent command line, for the preflight
	// disclosure only — the Invoker is what actually runs it.
	Agent []string
	// Root is the workspace root. Trigger paths named by the agent are
	// verified against this tree; empty drops them all — an unverified
	// name must not reach storage.
	Root string
	// OnPreflight receives the plan before the first agent call: what
	// would be sent, where, and roughly what it would cost.
	OnPreflight func(Preflight)
	// DryRun stops after the preflight: nothing is sent, marked, pruned,
	// or persisted. The Invoker may be nil on a dry run.
	DryRun bool
}

type PinKey = reviews.PinKey

type Preflight struct {
	// Agent is the command line each group's prompt would be piped to.
	Agent []string
	// Groups describes each evidence group that would be sent this run.
	Groups []GroupPlan
	// PromptChars totals the prompts exactly as they would be sent now.
	// Execution primes later prompts with labels learned from earlier
	// groups, so treat it as a close lower bound.
	PromptChars int
	// Findings counts the finding bodies across all planned groups.
	Findings int
	// BodyCap is the largest per-finding evidence cap across planned groups.
	// Groups share a fixed total budget, so smaller groups can show more
	// of each finding. Path metadata and body share this cap; dispatch
	// reapplies best-effort secret redaction before the body is sent.
	BodyCap int
}

type Result struct {
	GroupsTotal   int // candidate groups in the current corpus
	GroupsSkipped int // already distilled (signature known)
	GroupsRead    int // sent to the agent this run
	GroupsFailed  int // agent or parse errors (not marked; retried next run)
	GroupsPending int // new groups left unread (limit or region filter)
	PrunedStale   int // pending proposals dropped because their group changed
	// PromptChars/ReplyChars meter the run's agent traffic — the basis
	// for the ~token estimate shown to the user. Failed groups count
	// too: their cost was paid.
	PromptChars int
	ReplyChars  int
	Duration    time.Duration
	// Duplicates counts distilled patterns dropped as restatements of
	// something already pinned, proposed, or decided.
	Duplicates int
	Proposals  []model.Proposal
}

type ScopeAdvisory struct {
	// NotePath is the path the note names, outside the regions. It
	// exists in the working tree — a missing path is never a target.
	NotePath string

	// Partner is the co-change partner file that agrees with
	// NotePath: equal to it, or under it when NotePath is a
	// directory. Co-change names files; notes often name directories.
	Partner string

	// Evidence is the cited finding file whose partner agreed.
	Evidence string

	// Together counts the shared commits on the Evidence–Partner
	// edge, so the printed advisory can show its strength.
	Together int

	// Suggested is the pin's current region set with the trigger
	// region appended. Regions the trigger region contains leave
	// first: delivery regions form a union, so a contained region
	// adds nothing and wastes a cap slot. Survivors keep their order
	// — order only feeds the legacy region: field; pin identity
	// sorts regions. Nil when the result would still pass
	// maxRegions: the user decides what to remove.
	Suggested []string
}

type TriggerFact struct {
	Path     string // the stored trigger path
	Region   string // its exact delivery region; "" for vanished paths
	Together int    // strongest confirming co-change edge; 0 = unconfirmed
	Direct   bool   // true when the trigger is itself cited evidence
	Selected bool   // true when the recomputed delivery set reaches it
}