engine

type ActionRecord struct {
	Action string `json:"action"`
	OK     bool   `json:"ok"`
	Detail string `json:"detail,omitempty"`
	PR     int    `json:"pr,omitempty"`
	Commit string `json:"commit,omitempty"`
}

type Checker interface {
	Check(ctx context.Context) error
}

type Connection struct {
	Kind     string `json:"kind"` // forge or tracker
	Name     string `json:"name"`
	Provider string `json:"provider"`
	Host     string `json:"host"`
	OK       bool   `json:"ok"`
	Detail   string `json:"detail"`
}

type DecisionRecord struct {
	Input    decide.Input    `json:"input"`
	Decision decide.Decision `json:"decision"`
	Policy   PolicyRef       `json:"policy"`
}

type Engine struct {
	Store store.Store
	Forge forge.Forge
	// ForgeHost is Forge's host as item keys name it; default github.com.
	ForgeHost string
	// Forges are the forge instances besides Forge, by host, such as a GitHub Enterprise Server
	// (ADR-003). A repository on one is named host/owner/name; one on Forge, owner/name.
	Forges map[string]ForgeInstance
	// NewForge builds a forge instance the configuration repository declares; nil allows none.
	NewForge func(name string, cfg map[string]any) (ForgeInstance, error)
	// NewTracker builds a tracker instance the configuration repository declares, returning its
	// host; nil allows none.
	NewTracker func(name string, cfg map[string]any) (string, tracker.Tracker, error)
	// ConfigRepo is the factory's configuration repository (owner/name on the forge), whose
	// factory.yaml enrols repositories and whose lanes.yaml every enrolled repository's lanes
	// are laid over (ADR-006). Empty: Repos is the enrolment and each repository's lanes stand
	// alone.
	ConfigRepo string
	// Trackers are the tracker instances by host (ADR-003).
	Trackers map[string]tracker.Tracker
	Git      Git
	Executor func(name string) (executor.Executor, error)

	Repos       []string // enrolled repositories
	Lanes       []string // only these lanes; empty means all
	WorkDir     string
	Owner       string
	LeaseTTL    time.Duration
	Heartbeat   time.Duration
	Poll        decide.Poll
	RunTimeout  time.Duration
	Interactive bool // allows the process executor (ADR-007)

	// BuildImage builds a ynh agent image for a harness in a worktree (`ynh image --entrypoint
	// agent`) and returns its tag. Nil means ynh is not available (ADR-012).
	BuildImage func(ctx context.Context, worktree string, cfg policy.Ynh) (string, error)
	// HostAutoApprove is --auto-approve asked for by the person at the terminal (ynf start), for
	// runs on the host only; HostCapabilities reports the host ynh's capabilities to check it.
	HostAutoApprove  string
	HostCapabilities func(ctx context.Context) (string, error)
	// ImageHarness reads what the harness inside an agent image declares, by asking the image's
	// own ynh; harness picks one when the image carries several. nil skips reading it.
	ImageHarness func(ctx context.Context, image, harness string) (runner.Harness, error)
	// InstallHarness installs a harness, a folder or a pin from a repository, into the ynh home
	// ynhHome, which is the run's own, and says what was installed, including the id `ynh agent
	// run` takes for it. nil runs the lane's harness value as it is, which a pin cannot be.
	InstallHarness func(ctx context.Context, src runner.HarnessSource, ynhHome string) (runner.Installed, error)
	// ImageCapabilities reports the capabilities version of the ynh inside an agent image; nil
	// skips the check.
	ImageCapabilities func(ctx context.Context, image string) (string, error)
	// DetectYnh reports whether the host's ynh is there and supported, for a lane that names no
	// runner (ADR-012); the CLI passes runner.DetectedYnh, which asks once per process. Nil means
	// ynh is not detected, and a lane that names ynh is not checked against it.
	DetectYnh func(ctx context.Context) runner.Detection
	// Getenv reads the variables a lane passes into its runs (run.env). Default os.Getenv.
	Getenv func(string) string

	// Memory is ynm when it is configured or detected, else nil (ADR-008). It is advisory: what it
	// holds goes into a run's task and to people, never into a decision.
	Memory memory.Memory
	// MemoryNamespace is the namespace for a repository; default factory/<owner>/<name>.
	MemoryNamespace func(repo string) string
	// MemoryLevel is the ynm level ynf writes at: empty or personal for one person's store,
	// distributed for a shared one (ADR-008).
	MemoryLevel string
	// Spool is the spool root, when one is configured: each run gets a folder and a manifest in
	// it (ynr ADR-003). SpoolCollector is true when ynf starts ynr serve for the job, so runs
	// start without the operator's OTEL_EXPORTER_OTLP_*.
	Spool          *spool.Spool
	SpoolCollector bool
	// ProgressEvery is how often a run in progress is logged; default 30s, negative for never.
	ProgressEvery time.Duration

	Now   func() time.Time
	NewID func() string
	Log   *slog.Logger
	// Telemetry is ynf's OpenTelemetry (ADR-011); nil writes none and changes nothing. It is
	// write-only: nothing in the engine reads it back.
	Telemetry *telemetry.T
	// contains filtered or unexported fields
}

type FactoryPolicy struct {
	Repo  string
	SHA   string
	Dir   string
	File  *policy.Factory
	Lanes []byte // its lanes.yaml; empty when it has none
}

type ForgeInstance struct {
	Host    string
	Forge   forge.Forge
	Git     Git
	Tracker tracker.Tracker
}

type Git interface {
	Mirror(ctx context.Context, repo string) (string, error)
	Checkout(ctx context.Context, mirror, ref, dir string) (string, error)
	RemoveCheckout(dir string) error
	RemoteHas(ctx context.Context, mirror, branch string) bool
	Changed(ctx context.Context, wt string) ([]string, error)
	Commit(ctx context.Context, wt, message string) (string, error)
	Push(ctx context.Context, wt, repo, branch string) error
	Head(ctx context.Context, wt string) (string, error)
	RemoteSHA(ctx context.Context, mirror, branch string) (string, error)
	PushFastForward(ctx context.Context, wt, repo, branch string) error
}

type LaneRun struct {
	Lane     string          `json:"lane"`
	Kind     string          `json:"kind"`
	On       bool            `json:"on"`
	Runner   string          `json:"runner"`             // the runner it runs: what it names, else what detection chose
	Detected bool            `json:"detected,omitempty"` // the lane names no runner, so Runner is what this host resolves to
	Resolves string          `json:"resolves,omitempty"` // what an unnamed runner resolves to here, such as "ynh (detected 0.10.0)"
	Executor string          `json:"executor"`
	Image    string          `json:"image,omitempty"`
	Harness  string          `json:"harness,omitempty"`  // what the lane names
	Model    string          `json:"model,omitempty"`    // the model the lane pins; empty is the vendor's default
	Effort   string          `json:"effort,omitempty"`   // the effort the lane asks for; empty is the harness's or vendor's default
	Where    string          `json:"where"`              // where the harness comes from
	Pin      *policy.Pin     `json:"pin,omitempty"`      // the repository and ref, for a harness pinned from one
	Resolved string          `json:"resolved,omitempty"` // what a pin installs: name@version at its commit
	Read     *runner.Harness `json:"read,omitempty"`     // the harness, when it could be read
	Problem  string          `json:"problem,omitempty"`  // why it could not be read, or does not fit the lane
}

type LaneState struct {
	Repo   string    `json:"repo"`
	Lane   string    `json:"lane"`
	Paused bool      `json:"paused"`
	Reason string    `json:"reason,omitempty"`
	By     string    `json:"by,omitempty"`
	At     time.Time `json:"at"`
}

type ModelStats struct {
	Model     string  `json:"model"`
	Effort    string  `json:"effort,omitempty"`
	Runs      int     `json:"runs"`
	Converged int     `json:"converged"`
	Turns     int     `json:"turns"`  // total, over runs that reported them
	Tokens    int     `json:"tokens"` // total, input and output
	CacheRead int     `json:"cache_read_tokens,omitempty"`
	CostUSD   float64 `json:"cost_usd,omitempty"`
	Proposed  int     `json:"proposed"`
	Merged    int     `json:"merged"`
	Rejected  int     `json:"rejected"`
}

type PolicyRef struct {
	Repo      string `json:"repo"`
	Dir       string `json:"dir"`
	Ref       string `json:"ref"`
	SHA       string `json:"sha,omitempty"` // the repository's commit its lanes were read at
	Config    string `json:"config,omitempty"`
	ConfigSHA string `json:"config_sha,omitempty"`
	Hash      string `json:"hash"`
}

type RefusedError struct{ Reason string }

type Replayed struct {
	EntryID  string          `json:"entry_id"`
	Event    string          `json:"event"`
	Recorded decide.Decision `json:"recorded"`
	Replayed decide.Decision `json:"replayed"`
	Same     bool            `json:"same"`
	Policy   string          `json:"policy"` // recorded, or the lane hash it was replayed under
}

type RepoPolicy struct {
	Repo     string
	Base     string // default branch
	SHA      string // the commit it was read at
	Dir      string // the factory folder it came from; empty when the repository has no lanes of its own
	Shadowed []string
	File     *policy.File
	// Config is the configuration repository's policy the lanes were laid over, if any; Own is
	// the repository's own lanes.yaml, for telling which layer set a value.
	Config *FactoryPolicy
	Own    []byte
}

type RequiredReport struct {
	Repo   string   `json:"repo"`
	Branch string   `json:"branch"`
	Known  bool     `json:"known"`
	Checks []string `json:"checks,omitempty"`
	Detail string   `json:"detail"`
	// Workflows is how many workflow files the default branch has, when the forge could say.
	Workflows *int `json:"workflows,omitempty"`
}

type RunRecord struct {
	RunID  string `json:"run_id"`
	Runner string `json:"runner"`
	// RunnerDetected is set when the lane named no runner and detection chose this one, so the
	// log and stats can tell a named runner from a detected one (ADR-012).
	RunnerDetected bool `json:"runner_detected,omitempty"`
	// RunnerFeatures are the features the host's ynh listed, for a run that was detected or ran a
	// harness folder by path, so the record says what the run could rely on.
	RunnerFeatures []string `json:"runner_features,omitempty"`
	Executor       string   `json:"executor"`
	Argv           []string `json:"argv"`
	Base           string   `json:"base"`
	Exit           int      `json:"exit"`
	Outcome        string   `json:"outcome"`
	Detail         string   `json:"detail,omitempty"`
	Changed        []string `json:"changed,omitempty"`
	Denied         []string `json:"denied,omitempty"` // hosts the egress proxy refused
	StepDir        string   `json:"step_dir"`
	Duration       string   `json:"duration"`
	// HarnessPin is the repository and ref a pinned harness was installed from, as the lane wrote
	// it; Harness and HarnessSHA say which harness and commit that gave.
	HarnessPin string `json:"harness_pin,omitempty"`
	// HarnessPinURL is the same pin as ynh was given it, set only when it differs: a bare host and
	// path (github.com/org/harness@v1) is cloned from https://github.com/org/harness.
	HarnessPinURL string `json:"harness_pin_url,omitempty"`
	// Model and Usage are what the runner reports, for comparing outcomes and cost by model and
	// effort (ADR-011). ynf's own store is the run history; memory holds only failure patterns.
	Model string `json:"model,omitempty"`
	runner.Usage
}

type ShadowGit interface {
	FirstParent(ctx context.Context, mirror, sha string) (string, error)
	RangeDiff(ctx context.Context, mirror, from, to string) (string, error)
	Diff(ctx context.Context, wt, base string) (string, error)
}

type ShadowRequest struct {
	Lane  string
	Repos []string // owner/name, as Policy takes them; empty: every enrolled repository with the lane
	// Since bounds how recently a candidate was closed; default 90 days.
	Since time.Duration
	// Limit is how many candidates to run per repository; default 20.
	Limit int
	// Tickets names candidates directly, in place of the lane's intake.
	Tickets []tracker.Ref
}

type StartRequest struct {
	Ref    tracker.Ref // the ticket; empty when Prompt is set
	Prompt string      // ad hoc work, with no ticket
	Labels []string    // the prompt's labels, as a ticket's would be: what the lane's templates read
	Repo   string      // owner/name on the forge; a GitHub issue's own repository when empty
	Lane   string      // empty: the repository's only originate lane
	Detach bool        // only record it, for a running ynf serve to step
}

type Stats struct {
	Repo       string         `json:"repo"`
	Lane       string         `json:"lane"`
	States     map[string]int `json:"states"`
	Proposed   int            `json:"proposed"` // items that ever had a pull request
	Merged     int            `json:"merged"`
	Rejected   int            `json:"rejected"` // pull requests closed without merging
	Yield      float64        `json:"yield"`    // merged ÷ (merged + rejected); -1 with no decided proposals
	Signatures map[string]int `json:"signatures"`
	Paused     bool           `json:"paused"`
	Reason     string         `json:"reason,omitempty"`
	// Models breaks the lane's runs down by model and effort (ADR-011): which can do the work,
	// at what cost. Read from ynf's own run records.
	Models []ModelStats `json:"models,omitempty"`
}

type Touched struct {
	Repo string `json:"repo"`
	// Host is the forge the event came from, read from the payload: github.com and an Enterprise
	// Server can share one endpoint. Empty when the payload does not say.
	Host   string `json:"host,omitempty"`
	Issues []int  `json:"issues,omitempty"`
	PRs    []int  `json:"prs,omitempty"`
}