loop

type Critic interface {
	Review(ctx context.Context, req ReviewRequest) (ReviewVerdict, error)
}

type Federated []channels.PatternSource

type Finding struct {
	HypothesisID string
	Statement    string
	Private      *artifact.Envelope
	Public       *artifact.Envelope

	// PriorArt lists local/federation matches for this finding's crash keys —
	// retrieval, re-grounded by the local oracle. Novel ⇒ nobody we can see
	// already holds this crash.
	PriorArt []channels.PriorArt
	Novel    bool
}

type Hypothesis struct {
	Statement string `json:"statement"`
}

type LocalSource struct {
	Store candidateIndex
}

type Loop struct {
	Store  *store.Store
	Model  model.Model
	Router router.Router
	Runner runner.Runner

	Gate *channels.Gate        // emit gate (anonymize → tier → re-id → self-verify)
	Sink channels.ArtifactSink // where vetted patterns go (M1: local outbox)

	// Signer, if set, client-signs emitted patterns.
	Signer ed25519.PrivateKey

	// Source, if set, is consulted at harvest for prior art matching a
	// confirmed crash's keys — the "down" query channel. It
	// classifies a finding (novel vs. rediscovery) and never gates the harvest.
	Source channels.PatternSource

	// Critic, if set, reviews a top-level dead-end (a scientist that gave up
	// without confirming or spawning) with fresh context; a "premature" verdict
	// yields one more child line (M3 governance).
	Critic Critic

	// Planner decomposes the objective into a hypothesis frontier. Defaults are
	// chosen by mode (copilot → SingleHypothesis; discover → ModelPlanner).
	Planner Planner
	// MaxParallel bounds concurrent scientists in discovery mode (default 4).
	MaxParallel int

	// WorkspaceRoot is where per-run agent workspaces are created.
	WorkspaceRoot string

	// AgentImage, if set (and digest-pinned), runs each scientist's exec in an
	// isolated container instead of on the host. DockerBin overrides
	// the docker binary. Unset → host exec (not a security boundary).
	AgentImage string
	DockerBin  string
	// SandboxNetwork is the sandbox docker network (default "none"); a named
	// network is the scoped tool-broker hole.
	SandboxNetwork string

	// Catalog, if non-empty, surfaces role-scoped pinned tools to the agent via
	// the broker. Its pinned set is recorded in every emitted
	// artifact's provenance so a replay re-provisions identically.
	Catalog   toolcat.Catalog
	AgentRole string // role scope for catalog tools (default "exploit-dev")

	// Now supplies timestamps for artifacts (defaults to time.Now).
	Now func() time.Time
	// Log receives short progress lines (optional).
	Log func(string)
}

type Metrics struct {
	Confirmed         int           // oracle-verified findings
	Novel             int           // findings nobody (local or commons) already held
	Rediscoveries     int           // findings that matched prior art (retrieval hit)
	TotalTokens       int           // prompt + completion across every scientist
	CostUSD           float64       // proxy-reported spend
	Elapsed           time.Duration // supervisor wall-clock
	Iterations        int           // total ReAct iterations across the frontier
	TokensPerFinding  int           // TotalTokens / Confirmed (0 when nothing confirmed)
	SecondsPerFinding float64       // Elapsed / Confirmed
	PriorArtHitRate   float64       // Rediscoveries / Confirmed — commons/local retrieval effectiveness
}

type ModelCritic struct {
	Model  model.Model
	Router router.Router
}

type ModelPlanner struct {
	Model  model.Model
	Router router.Router
}

type PlanRequest struct {
	Objective  string
	TargetDesc string
	Mode       string // discover | copilot
	Max        int
}

type Planner interface {
	Plan(ctx context.Context, req PlanRequest) ([]Hypothesis, error)
}

type Report struct {
	RunID          string
	Confirmed      bool
	StopReason     string
	Iterations     int
	Usage          model.Usage
	Findings       []Finding
	Hypotheses     int // how many were on the frontier
	RuledOut       string
	PoVSubmissions int

	// Private/Public mirror the first finding for single-finding (copilot) use.
	Private *artifact.Envelope
	Public  *artifact.Envelope

	// Elapsed is the supervisor wall-clock for the whole run (instrumentation:
	// the speed half of the token/speed claims).
	Elapsed time.Duration
}

type Request struct {
	Objective  string
	Mode       string // "discover" | "copilot"
	TargetRef  string
	TargetDesc string

	Oracle oracle.Spec
	Base   runner.RunSpec  // authoritative target run template
	Fixed  *runner.RunSpec // optional differential fixed-image template

	MaxIters         int
	HypothesisBudget int

	// M2 frontier controls.
	MaxHypotheses int // planner cap (discovery); default 6, copilot forces 1
	GlobalBudget  int // total scientist iterations across the frontier; 0 → derived

	// M3 governance: per-scientist token budget and stall limit.
	TokenBudget int // halt a scientist once it spends this many tokens (0 → unlimited)
	StallLimit  int // halt after this many no-progress iterations (0 → default)

	// Context compaction (context compaction): reproject the working
	// context onto a bounded digest over the durable trajectory when the estimated
	// prompt exceeds ContextBudget tokens, so a scientist runs long instead of
	// halting when history fills. 0 → disabled. KeepRecent turns kept verbatim (0 → 6).
	// Compactor selects the strategy: "" / "template" (deterministic, 0 tokens,
	// default) or "model" (adds a cheap-tier narrative of the compacted turns).
	ContextBudget int
	KeepRecent    int
	Compactor     string

	// MaxDepth bounds sub-hypothesis backtracking: a scientist may spawn child
	// lines the supervisor dispatches in the next wave, down to this depth (M2).
	// 0 → default 2 (top-level + two levels of children).
	MaxDepth int

	// SeedFiles are host file paths copied into each scientist's workspace before
	// it runs — e.g. the target's source for a WHITE-BOX audit (the agent can
	// read_file it), the realistic "audit arbitrary code" scenario.
	SeedFiles []string
}

type ReviewRequest struct {
	Objective  string
	StopReason string
	Summary    string // the scientist's final message / conclusion
}

type ReviewVerdict struct {
	Adequate   bool   `json:"adequate"`
	Reason     string `json:"reason"`
	Suggestion string `json:"suggestion"`
}

type SingleHypothesis struct{}