session

type Recovery struct {
	Leads        int
	Reservations int
	Sessions     int
	// Documents is stored source text deleted for being past its TTL. Reclaimed
	// disk rather than recovered state, and reported for the same reason: a
	// number nobody prints is a sweep nobody notices has stopped running.
	Documents int64
}

type Result struct {
	Session *core.Session

	// Run is the loop's own result. Nil when the loop never started.
	Run *executor.Result
	// Report is the synthesized answer. Nil when generation failed — never fatal,
	// since a failed synthesis costs the prose and not the evidence.
	Report *output.Report
	// Ground is §11.5.2's pass. Nil when it did not run.
	Ground *verifier.GroundReport

	// Status is what the session was finalized as.
	Status core.SessionStatus
	// Err is the loop's error. Returned in the struct rather than as the
	// function's error because a failed loop still has a session, a spend, and
	// usually claims — a caller that gets only an error has to go and find them.
	Err error
}

type Runner struct {
	Store store.Store
	Actor *actors.WebActor

	// VerifierModel overrides the cheap model for adjudication. Empty leaves the
	// cheap model in place; set it when the cheap model cannot tell a
	// contradiction from two unrelated statements.
	VerifierModel string
	// VerifierBatchSize caps pairs per adjudication call. Zero takes the default.
	VerifierBatchSize int

	// NoConfirmEdges disables the second adjudication pass. Phrased as an opt-OUT
	// because confirming is the measured default and the flag exists for somebody
	// who has measured differently on their own data.
	NoConfirmEdges bool

	// Academic researches scholarly leads (§10.2). Nil disables the actor.
	//
	// Nil in two cases, not one: an install with no contact email (§10.3 makes
	// that a hard requirement), and every daemon — `mole serve` does not build
	// it, so the academic path is CLI-only today.
	Academic *actors.AcademicActor

	// Local answers leads from the user's own registered data (§12). Nil
	// disables the actor, which is the state of any install where nobody has
	// run `mole connect add`.
	Local *actors.LocalComputeActor

	// Owner names what is running the loop, for lead leases (§9.4). A daemon and
	// a CLI must not claim each other's leads.
	Owner string

	Log *slog.Logger

	// Progress receives executor events as they happen.
	Progress func(executor.Event)
	// OnLoop fires when the research loop finishes, before any escrow is released.
	// OnGround fires when the grounding pass finishes, before the report is
	// generated.
	//
	// Callbacks rather than fields on Result because the sequence is observable
	// and Result is not: the CLI prints the run summary, then grounding, then the
	// report, in that order. Returning all three at the end collapses that into
	// one moment and the caller has to guess the order — which is exactly what
	// went wrong when this package was first extracted, and the grounding line
	// started printing ahead of the summary it follows.
	//
	// A daemon uses the same two points to publish status transitions without
	// waiting for the report.
	OnLoop   func(*executor.Result)
	OnGround func(*verifier.GroundReport)
	// Notice receives non-fatal problems: a sweep that failed, a hold that could
	// not be released, a report that would not generate. None of these stops a
	// run, and all of them need saying. The CLI writes them to stderr; a daemon
	// logs them.
	Notice func(string)
}

type Spec struct {
	Question   string
	Mode       core.Mode
	BudgetUnit core.BudgetUnit
	Budget     int64

	// MaxSources is sources read per lead; MaxDepth is rounds of follow-up leads
	// the planner may add; MaxLeads bounds the whole session (§8.5).
	MaxSources int
	MaxDepth   int
	MaxLeads   int

	// Timeout is the session's wall-clock ceiling (§8.5). The caller owns the
	// context deadline; this is the ceiling the loop checks itself against, and
	// the two should not be equal — see Runner.Run.
	Timeout time.Duration

	// Schema is the dataset schema, required when Mode is ModeDataset and unused
	// otherwise (M9, §13).
	Schema *dataset.Schema

	// ActorTypes are the actors this session may use. Empty means web only.
	//
	// Session-level rather than planner-chosen: the actor has to be provably
	// working before the planner starts making choices about it, and a session
	// that never asked for academic sources should never pay for one.
	ActorTypes []core.ActorType

	// Workers is how many leads this session runs at once. Zero takes
	// executor.DefaultWorkers. Not persisted on the session row: it is a
	// property of the process doing the work, not of the research, and a
	// recovered session is re-run by whatever is configured then.
	Workers int
}

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