services

type All interface {
	Reader
	Setup
	Decisions
	Learning
	Maintenance
	Settings
}

type Decisions interface {
	// PreviewDecision describes a proposal decision. It writes nothing.
	PreviewDecision(action proposals.Action, ids []int64) (*proposals.Preview, error)
	// CommitDecision revalidates and applies a reviewed decision.
	CommitDecision(p *proposals.Preview) (proposals.Result, error)
}

type Deps struct {
	// Fetch reads the GitHub review comments; nil runs gh.
	Fetch reviews.FetchFunc
	// Invoke sends the distillation and the trigger extraction prompts;
	// nil runs the command of the reviewed preview.
	Invoke agent.Invoker
	// Now reads the clock; nil reads the system clock.
	Now func() time.Time
}

type IndexEvent struct {
	Phase string
	Done  int
	Total int
	// Log is a warning or note line; Phase is then empty.
	Log string
}

type IndexView struct {
	Probe workspace.IndexProbe
	// Status is nil unless Probe.State is IndexReady and Gather worked.
	Status *status.Status
	// StatusErr holds the semantic health read failure.
	StatusErr error
	// Policy summarizes the gate policy. It does not need the index, so
	// it is filled in every index state.
	Policy PolicySummary
}

type Learning interface {
	// Learning reads the stored evidence, the review target, and the
	// review window. It runs local git only; it never fetches or writes.
	Learning() learning.Snapshot

	// PlanEvidence previews an evidence refresh in mode. It fetches
	// nothing and writes nothing.
	PlanEvidence(mode index.SourceMode) (*learning.Plan, error)
	// RunEvidence runs exactly the reviewed plan. A stop through ctx
	// ends the GitHub fetch; progress runs on the worker goroutine.
	RunEvidence(ctx context.Context, p *learning.Plan, progress func(index.RefreshEvent)) (learning.Outcome, error)
	// PlanDistill previews a distillation. It never runs the agent and
	// never writes.
	PlanDistill(req learning.DistillRequest) (*learning.DistillPreview, error)
	// RunDistill runs exactly the reviewed preview. A stop through ctx
	// starts no new group; progress runs on the worker goroutine.
	RunDistill(ctx context.Context, p *learning.DistillPreview, progress func(distill.Event)) (*distill.Execution, error)
	// CleanupPending removes the stale pending proposals of a
	// cleanup-only preview. It runs no agent.
	CleanupPending(p *learning.DistillPreview) (int, error)
	// PlanExtract previews a trigger extraction of the selected
	// proposals. It never runs the agent and never writes.
	PlanExtract(req learning.ExtractRequest) (*learning.ExtractPreview, error)
	// RunExtract runs exactly the reviewed preview. A stop through ctx
	// starts no new batch; progress runs on the worker goroutine.
	RunExtract(ctx context.Context, p *learning.ExtractPreview,
		progress func(distill.ExtractEvent)) (*distill.ExtractExecution, error)
}

type Maintenance interface {
	// Pins reads the installed pins of .seamark/lessons.yaml and relates
	// them to the ledger. It needs no index and never fails: a file or
	// ledger problem is data in the inspection. It writes nothing.
	Pins() *maintain.Inspection
	// PlanMaintenance plans a retarget or a prune of the selected pins.
	// It writes nothing.
	PlanMaintenance(req maintain.Request) (*maintain.Plan, error)
	// CommitMaintenance revalidates and commits exactly the reviewed plan.
	CommitMaintenance(p *maintain.Plan) (maintain.Result, error)
	// PlanRecovery plans the ledger-only completion of a partial
	// maintenance operation of this session. It writes nothing.
	PlanRecovery(r *maintain.Recovery) (*maintain.Plan, error)
	// CommitRecovery revalidates the recovery proof and completes the
	// ledger update. It never writes the pin file.
	CommitRecovery(p *maintain.Plan) (maintain.Result, error)
	// PlanAuthor plans the create, edit, or removal of one pin. It
	// writes nothing. A missing ledger or a foreign root is a blocker
	// of the plan, not an error.
	PlanAuthor(req maintain.AuthorRequest) (*maintain.AuthorPlan, error)
	// CommitAuthor revalidates and writes exactly the reviewed pin file
	// bytes. It never writes the ledger, and it refuses a foreign root
	// with ErrForeignRoot.
	CommitAuthor(p *maintain.AuthorPlan) (maintain.AuthorResult, error)
}

type PolicySummary struct {
	Mode     string
	Deny     int
	Approval int
	Err      error
}

type Reader interface {
	// Root returns the effective repository root.
	Root() string
	// DBPath returns the index database path.
	DBPath() string
	// Version returns the seamark version.
	Version() string

	// Fresh reports a workspace without any Seamark state: no index
	// database, no .seamark directory, and no recognized integration
	// artifact.
	Fresh() (bool, error)
	// Doctor runs the installation checks of `seamark doctor`.
	Doctor() *doctor.Report
	// Index probes the index and gathers semantic health when ready.
	Index() IndexView
	// Integrations inspects every registered client.
	Integrations() []integration.Inspection
	// Clients returns the registered client descriptors.
	Clients() []integration.Client
	// AgentsOnPath returns the IDs of the registered clients whose agent
	// command is on PATH. It never runs an agent.
	AgentsOnPath() []string
	// Ledger reads the proposal decision ledger.
	Ledger() (*proposals.Ledger, error)
	// Stats reads the lesson delivery statistics.
	Stats() lessonstats.Snapshot
	// Sample runs the lesson selection of one surface for explicit
	// paths under the two lessons.yaml texts of one review. It never
	// emits, records, or leases delivery, and it never builds the index.
	Sample(req SampleRequest) SampleView
}

type SampleRequest struct {
	Surface SampleSurface
	// Paths are the paths to sample, in the order of the user. They are
	// user text.
	Paths []string
	// Before and After are lessons.yaml texts. Before also decides Stale.
	Before, After []byte
}

type SampleSurface int

type SampleView struct {
	Surface SampleSurface
	// Paths are the files that the selection uses, named by the rule of
	// the surface. The hook gives its normalized files. change_set gives
	// one name per requested path, repeats kept. Paths is nil when the
	// sample is unavailable before the naming.
	Paths []string
	// Rejected are the paths that the hook rejects, as NormalizePaths
	// keeps them: at most its first few. change_set rejects no path.
	Rejected []delivery.RejectedPath
	// Unindexed are the entries of Paths that the index does not know,
	// by the rule of report.ChangeSetNames, for both surfaces. They are
	// a label only: a new file still matches by path.
	Unindexed []string
	// NoFile are the entries of Paths that name no existing file or
	// directory, a future path for example. A relative entry resolves
	// against the effective root. They are a label only: a lesson can
	// match a path that does not exist yet.
	NoFile []string
	// Current is the selection under Before, Candidate under After.
	Current, Candidate report.Selection
	// CurrentThreshold and CandidateThreshold are the thresholds of the
	// two configurations, as the lessons reader decodes them. An
	// exclusion says only that a lesson is below the threshold, so a
	// view needs the number to name it. Both are zero until both texts
	// parse.
	CurrentThreshold, CandidateThreshold int
	// Unavailable states why the sample computes no selection, as one
	// text that starts with "Sample unavailable: ". It is empty when the
	// sample computes both selections.
	Unavailable string
	// IndexedAt is the time of the last index run; zero when unknown.
	// ReadAt is the start time of the evidence read; zero when no read
	// succeeded.
	IndexedAt, ReadAt time.Time
	// Stale is true when lessons.yaml under the effective root no longer
	// holds Before. The saved side of the sample is then not the disk.
	Stale bool
}

type Settings interface {
	// Settings reads the focused settings of both documents. The error
	// reports invalid arguments only; a file problem or a foreign root
	// is data in the snapshot.
	Settings() (*settings.Snapshot, error)
	// PlanSettings plans a guarded patch of one settings group. It
	// writes nothing.
	PlanSettings(snap *settings.Snapshot, edits []settings.Edit) (*settings.Plan, error)
	// SaveSettings writes exactly the reviewed plan, or reports it stale.
	// A lessons save refuses a foreign root with ErrForeignRoot.
	SaveSettings(p *settings.Plan) (settings.Result, error)
}

type Setup interface {
	// PlanSetup plans an integration change. It writes nothing.
	PlanSetup(setups []integration.ClientSetup) (*SetupPreview, error)
	// ApplySetup applies exactly the reviewed plan.
	ApplySetup(p *SetupPreview) (integration.SetupResult, error)
	// BuildIndex runs a local index build. It cannot be cancelled.
	BuildIndex(force bool, progress func(IndexEvent)) (*index.Summary, error)
}

type SetupPreview struct {
	Setups   []integration.ClientSetup
	Plan     *integration.SetupPlan
	Writes   []integration.WritePreview
	GateMode string
	// PlannedAt is the plan time; the result screen reports it.
	PlannedAt time.Time
}