executor

type Class int

type Event struct {
	Phase string // "planning", "executing", "replanning", "lead", "cached"
	// Detail is a short human-readable note, already formatted.
	Detail string
}

type Executor struct {
	Store   store.Store
	Ledger  *budget.Ledger
	Queue   *queue.Queue
	Planner *planner.Planner

	// Verifier builds the claim graph (§11). Nil skips verification entirely,
	// which is a supported configuration: the research still runs, claims still
	// carry verified quotes, and derived confidence stays 0 rather than being
	// invented.
	Verifier *verifier.Verifier
	Actors   map[core.ActorType]actors.Actor
	Log      *slog.Logger

	// Owner identifies the PROCESS holding a lease — "cli" or "daemon" — so the
	// two never claim each other's leads (§9.4).
	//
	// Not per worker, despite what this said before the pool existed. Workers in
	// a session share it, and nothing wants otherwise: a lease is claimed for a
	// specific lead in a transaction, so the lead is already the unit of
	// identity, and the heartbeat renews that lease rather than anything owned
	// by a worker. Boot recovery sweeps by age across all owners.
	Owner string

	// Workers is how many leads this session runs at once. Zero takes
	// DefaultWorkers.
	//
	// Per session rather than per process: the supervisor already bounds how many
	// sessions run at once, and one shared pool would let a single large session
	// starve every other one. The product of the two is what a person actually
	// has to reason about — at the defaults, four sessions of three workers is
	// twelve concurrent leads and twelve outbound fetches — so both numbers stay
	// visible instead of being folded into one.
	Workers int

	// Progress reports phase transitions as they happen. Optional.
	//
	// Not decoration. Planning is a single model call with no output until it
	// returns, and on a local model that is minutes of silence — three runs were
	// killed by hand because the CLI printed a header and then nothing, which
	// reads as a hang rather than as work.
	Progress func(Event)

	// Cache holds artifacts already researched in this session (§9.3). Shared
	// with the actor, so a lead-level hit and a URL-level hit are the same
	// cache and one lead's fetches serve another's.
	Cache *cache.Cache

	// Pricing and CheapModel convert a USD reservation into the token ceiling
	// an actor can act on. CheapModel names the tier chunk mining actually
	// uses; pricing the ceiling off the strong model would set it several
	// times too low. Both empty leaves the actor's configured budget in place.
	Pricing    *pricing.Table
	CheapModel string

	// Estimator sizes reservations. Nil uses a fresh one for the session's
	// budget unit.
	Estimator *budget.Estimator

	// Now and Jitter are injectable for tests.
	Now    func() time.Time
	Jitter func() float64

	// Sleep waits between retries. Injectable so a test does not spend the
	// backoff in real time.
	Sleep func(context.Context, time.Duration) error
}

type Result struct {
	SessionID string
	Status    core.SessionStatus

	Digest *planner.Digest
	Claims []core.Claim

	LeadsRun    int
	LeadsFailed int
	LeadsCached int
	Replans     int

	// CacheStats reports whether the cache earned its keep. An unmeasured
	// cache is an assumption.
	CacheStats cache.Stats

	// Verification totals across every pass (§11).
	VerifyPasses    int
	ClaimsVerified  int
	EdgesWritten    int
	Contradictions  int
	FollowUpsQueued int
	// VerifyDegraded is the last reason a pass could not finish, if any.
	VerifyDegraded string

	// Spent is the settled total in the session's budget unit.
	Spent int64
	// StoppedBecause names the ceiling or condition that ended the run, for
	// the report and the trace.
	StoppedBecause string
}