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 Duplicate struct {
	// Rule is the dropped pattern's label.
	Rule string
	// Of is the label of the known pattern it restates.
	Of string
}

type Event struct {
	Kind EventKind
	// Index is the 0-based position in Plan.Groups. For EventStopped it
	// is the first group that did not run.
	Index int
	// Total is len(Plan.Groups), a known denominator for progress.
	Total int
	// Group is set on EventGroupStarted.
	Group *GroupPlan
	// Outcome is set on EventGroupFinished.
	Outcome *GroupOutcome
	// Dup is set on EventDuplicate.
	Dup *Duplicate
	// Removed is set on EventCleanupDone.
	Removed int
	// Stop and Err are set on EventStopped.
	Stop StopReason
	Err  error
}

type EventKind int

type ExecuteOptions struct {
	// Progress receives events synchronously on the executing goroutine,
	// never while a transaction is open. A slow receiver delays the next
	// group, not the current agent call. Nil discards the events.
	Progress func(Event)
	// Revalidate runs before the cleanup and before each group. A
	// non-nil error stops the run with StopConflict. A service passes
	// its file and workspace checks here. Nil checks nothing.
	Revalidate func() error
	// Boundary turns on the store checks: the full plan revalidation
	// before the cleanup, the per-group checks before each group, and
	// the guarded save that refuses a group another writer recorded.
	Boundary bool
	// SkipCleanup leaves the planned cleanup undone. The legacy Run
	// sets it, because it already pruned during planning.
	SkipCleanup bool
}

type Execution struct {
	// Groups are the outcomes, parallel to Plan.Groups.
	Groups []GroupOutcome
	// CleanupIDs are the planned cleanup rows.
	CleanupIDs []int64
	// Removed counts the rows the cleanup actually deleted. A row that
	// another writer decided meanwhile stays, so it can be lower.
	Removed int
	Stop    StopReason
	StopErr error
	// Result holds the legacy counters, derived from the outcomes.
	Result Result
}

type ExtractBatch struct {
	// Proposals are the frozen rows in send order. The question sends
	// their recorded rule and note, and their guards bind the answers.
	Proposals []model.Proposal
	// Items are parallel to Proposals.
	Items []ExtractItem
	// Prompt is the exact text that ExecuteExtract sends.
	Prompt      string
	PromptChars int
}

type ExtractBatchOutcome struct {
	// Index is the position in ExtractPlan.Batches.
	Index   int
	Status  ExtractBatchStatus
	Failure FailureKind
	// Err is the cause of a failed or cancelled batch. It can hold agent
	// output, so a surface must sanitize and redact it.
	Err error
	// Items are parallel to the planned batch's proposals.
	Items []ExtractItemOutcome
	// Named counts the items whose answer in a valid reply names a path
	// that the syntax rung accepts. It counts the whole reply before any
	// write, so a store failure in the batch does not lower it. The CLI
	// prints it in the batch outcome line, as it did before a write.
	Named int
	// PromptChars and ReplyChars meter the agent traffic. They stay 0
	// when no agent call started for the batch.
	PromptChars int
	ReplyChars  int
	// Started and Finished bound the batch's work. Both are zero for an
	// unattempted batch.
	Started  time.Time
	Finished time.Time
}

type ExtractBatchStatus int

type ExtractEvent struct {
	Kind ExtractEventKind
	// Index is the 0-based position in ExtractPlan.Batches. For
	// ExtractStopped it is the first batch that did not run.
	Index int
	// Total is len(ExtractPlan.Batches), a known denominator.
	Total int
	// Batch is set on ExtractBatchDone. It points to a deep copy, slices
	// included, so a receiver on another goroutine never shares memory
	// with the run. Only Err values are shared, because errors are
	// immutable.
	Batch *ExtractBatchOutcome
	// Stop and Err are set on ExtractStopped.
	Stop StopReason
	Err  error
}

type ExtractEventKind int

type ExtractExecuteOptions struct {
	// Check runs before the first batch and before each batch: the
	// caller's cheap checks, such as the file hashes and the invocation.
	// A non-nil error stops the run with StopConflict. Nil checks nothing.
	Check func() error
	// OnEvent receives events synchronously on the executing goroutine,
	// never while a transaction is open. Nil discards the events.
	OnEvent func(ExtractEvent)
	// Now is the clock for the stamps and the batch times. Nil means
	// time.Now.
	Now func() time.Time
}

type ExtractExecution struct {
	// Batches are the outcomes, parallel to ExtractPlan.Batches.
	Batches []ExtractBatchOutcome
	Stop    StopReason
	StopErr error
	// Persisted lists the items with a stored answer, positive or
	// negative. The other lists name the items in each remaining class.
	// Every list is in send order.
	Persisted   []int64
	Failed      []int64
	Cancelled   []int64
	Conflicts   []int64
	Unattempted []int64
	// Result holds the legacy counters, derived from the outcomes.
	// Examined counts the items of the batches whose agent call started.
	Result ExtractResult
}

type ExtractItem struct {
	// ID is the proposal ID, equal to the parallel proposal's ID.
	ID int64
	// Reason says why the question is open.
	Reason TriggerReason
	// Living are the member findings that are still in the index, with
	// metadata only. Region recomputation reads these frozen values.
	Living []model.Finding
	// Evidence are the evidence paths that the prompt names for the item,
	// after the shared batch budget.
	Evidence []string
	// Coverage is the evidence coverage of a pending row. A negative or
	// unconfirmed answer gives the row this region set. It is nil for an
	// applied row, whose regions never change here.
	Coverage []string
	// CoverageChanges reports that Coverage differs from the stored
	// regions of a pending row, so a negative answer changes them.
	CoverageChanges bool
	// contains filtered or unexported fields
}

type ExtractItemOutcome struct {
	// Proposal is the row as planned.
	Proposal model.Proposal
	Status   ExtractItemStatus
	Failure  FailureKind
	// Err is the cause of a failed, cancelled, or conflicting item. It can
	// hold agent output, so a surface must sanitize and redact it. It is
	// nil for a stored answer.
	Err error
	// Omitted is true when a valid reply had no entry for the item. The
	// prompt asks the model to list only the items that qualify, so the
	// item is a stored negative answer (D-19). A surface shows "omitted"
	// as the reason of that negative.
	Omitted bool
	// NamedRaw counts the paths of the item's answer as the model wrote
	// them. An answer of only invalid paths stays visible this way.
	NamedRaw int
	// Named are the answer's paths after the syntax rung.
	Named []string
	// Valid are the named paths that exist in the working tree. They are
	// the stored paths when Status is ExtractStored.
	Valid []string
	// Facts describe each valid path under today's history: direct,
	// confirmed by co-change, or unverified, and selected or not.
	Facts []TriggerFact
	// RegionsBefore and RegionsAfter are the effective region sets before
	// and after the answer. They differ only for a pending row whose
	// regions this run changed; an applied row keeps its regions.
	RegionsBefore  []string
	RegionsAfter   []string
	RegionsChanged bool
}

type ExtractItemStatus int

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 ExtractPlan struct {
	Options ExtractPlanOptions
	// Batches are the agent calls in execution order. NewExtractPlan sends
	// pending rows newest first, then applied rows newest first, as the
	// CLI orders them. ExtractTriggers keeps the order of its caller.
	Batches []ExtractBatch
	// Ineligible lists the selected proposals that are not asked, in
	// ascending ID order.
	Ineligible []ExtractSkip
	Snapshot   ExtractSnapshot
	// Preflight is the disclosure total. Its BodyCap is 0, because the
	// plan reads finding metadata only and sends no finding text. The
	// CLI disclosure of ExtractTriggers keeps its excerpt cap, because
	// its goldens pin that text (A0 defect D4).
	Preflight ExtractPreflight
	PlannedAt time.Time
}

type ExtractPlanOptions struct {
	// IDs are the explicitly selected proposals. The plan never adds a
	// proposal, so an empty list plans no call.
	IDs []int64
	// Root is the workspace root. Named paths are verified against this
	// tree. NewExtractPlan refuses "" (see ErrExtractRoot).
	Root string
	// Spec is the agent invocation the plan discloses. ExecuteExtract
	// runs the invoker its caller passes, so the caller must build that
	// invoker from this spec.
	Spec agent.CommandSpec
	// Exclude adds the caller's own exclusions, such as an absent or
	// ambiguous pin. It runs only for pending and applied rows whose
	// question is open. It returns the reason and true to exclude the
	// row. Nil excludes nothing more.
	Exclude func(model.Proposal) (reason string, excluded bool)
}

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)
	// Conflicts counts the proposals that another writer changed during
	// their agent call. The run discarded their answers and wrote nothing
	// to them.
	Conflicts int
	// Unattempted counts the proposals that a stop left unsent. The run
	// wrote nothing to them, so a later run can ask them.
	Unattempted int
	PromptChars int
	ReplyChars  int
	Duration    time.Duration
}

type ExtractSkip struct {
	ID     int64
	Reason string
}

type ExtractSnapshot struct {
	Rows     [32]byte
	Findings [32]byte
}

type FailureKind int

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 GroupOutcome struct {
	// Plan is the group's preflight entry.
	Plan    GroupPlan
	Status  GroupStatus
	Failure FailureKind
	// Err is the cause of a failed, cancelled, or skipped group. It can
	// hold agent output, so a surface must sanitize and redact it.
	Err error
	// Proposals are the persisted rows with their IDs.
	Proposals  []model.Proposal
	Duplicates []Duplicate
	// PromptChars and ReplyChars meter the agent traffic. They stay 0
	// when no agent call started for the group.
	PromptChars int
	ReplyChars  int
	// Started and Finished bound the group's work. Both are zero for an
	// unattempted group.
	Started  time.Time
	Finished time.Time
}

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

type GroupStatus int

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 Plan struct {
	Options PlanOptions
	// Preflight is the disclosure of the selected groups. It is the
	// same value that the legacy OnPreflight callback receives.
	Preflight Preflight
	// Groups are the selected groups in execution order, parallel to
	// Preflight.Groups.
	Groups []PlannedGroup
	// Cleanup lists the pending proposals whose evidence group no longer
	// exists. Execute deletes exactly these rows before the first group.
	Cleanup []model.Proposal
	// Skipped lists the signatures already distilled, in coverage order.
	Skipped []string
	// Deferred lists the groups beyond the limit, in coverage order. An
	// entry carries identity and size only: Signature, Region, Findings,
	// and BodyCap. Its prompt is not built, so PromptChars and Evidence
	// stay empty.
	Deferred []GroupPlan
	// Total counts every group in scope, skipped and deferred included.
	Total int
	// Corpus counts the findings in scope before grouping. Findings
	// without a group are not sent, and this count makes that visible.
	Corpus    int
	Snapshot  Snapshot
	PlannedAt time.Time
	// contains filtered or unexported fields
}

type PlanOptions struct {
	// Region restricts the corpus before grouping. It must already be
	// repository-relative, as NormalizeRegion returns it; "" means the
	// whole repository.
	Region string
	// Limit caps how many new groups the plan selects; 0 selects all.
	// NewPlan rejects a negative limit.
	Limit int
	// Pins are the patterns of .seamark/lessons.yaml as proposals, as
	// PinsFromConfig returns them.
	Pins []model.Proposal
	// Spec is the agent invocation the plan discloses. Execute runs the
	// invoker its caller passes, so the caller must build that invoker
	// from this spec.
	Spec agent.CommandSpec
	// Root is the workspace root. Trigger paths are verified against
	// this tree; "" drops them all.
	Root string
}

type PlannedGroup struct {
	Group Group
	// Digest identifies the member findings as the prompt would show
	// them. A boundary check compares it with the stored rows.
	Digest [32]byte
}

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
	// StalePending lists the IDs of the stale pending proposals that a
	// real run prunes first. Only a dry run fills it, because it plans
	// as if they were gone but must not delete them.
	StalePending []int64
	// 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 ScopeAdvice struct {
	Kind ScopeKind
	// Regions is the computed set in the order of the region engine. Nil
	// means repository-wide. It is nil for ScopeNoEvidence too; RepoWide
	// tells the two cases apart.
	Regions []string
	// Facts are the trigger facts of RecomputeRegions: which stored
	// trigger paths the evidence or the history confirms, and which of
	// them the region set delivers.
	Facts []TriggerFact
	// RepoWide is true when the computed set is repository-wide.
	RepoWide bool
	// Broader is true for a change that reaches a path the recorded set
	// does not reach. A preview shows it as a warning.
	Broader bool
	// Narrower is true for a change that no longer reaches a path the
	// recorded set reaches.
	Narrower bool
}

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 ScopeKind int

type Snapshot struct {
	// Corpus covers the findings in scope, with every field that reaches
	// grouping or the prompt.
	Corpus [32]byte
	// Ledger covers every stored proposal: the cleanup set, the known
	// patterns for deduplication, and the coverage order all read it.
	Ledger [32]byte
	// Distilled covers the recorded group signatures, the skip set.
	Distilled [32]byte
	// Pins covers PlanOptions.Pins. The store holds no pins, so
	// Revalidate does not check it; the caller guards the pin file.
	Pins [32]byte
}

type StopReason int

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
}

type TriggerReason int