upgrade

type ArtifactVerifier struct{ Resolver release.ArtifactResolver }

type Candidate struct {
	Kind      string `json:"kind"`
	Harness   string `json:"harness,omitempty"`
	Package   string `json:"package,omitempty"`
	Provider  string `json:"provider,omitempty"`
	Alias     string `json:"alias,omitempty"`
	From      string `json:"from"`
	To        string `json:"to"`
	Artifacts int    `json:"artifacts,omitempty"` // verified install artifacts (cli)
	Verdict   string `json:"verdict,omitempty"`   // gate verdict, or "" when not evaluated
	PR        string `json:"pr,omitempty"`
	Note      string `json:"note,omitempty"`

	// File and Edit are the candidate pin: the policy file it changes and how
	// to re-apply it to a given version of that file.
	File string                       `json:"file,omitempty"`
	Edit func([]byte) ([]byte, error) `json:"-"`
}

type Config struct {
	// Profile is the profile whose harness pins are upgrade candidates
	// (typically the "-next" profile ring1 canaries).
	Profile string `yaml:"profile"`
	// Suite is the eval suite run for each candidate.
	Suite string `yaml:"suite"`
	// Harnesses limits which pinned harnesses are watched (default: all
	// pinned harnesses with a known package).
	Harnesses []string `yaml:"harnesses,omitempty"`
	// Models are provider model lists to watch.
	Models []ModelSource `yaml:"models,omitempty"`
	// Base is the PR base branch (default: repo default).
	Base string `yaml:"base,omitempty"`
	// State is the watcher's memory on disk (default .halos/upgrade-state.json).
	State string `yaml:"state,omitempty"`
}

type EvalFunc func(ctx context.Context, c Candidate) (*eval.Scorecard, error)

type HTTPModels struct {
	URL, APIKey string
	HTTP        *http.Client
}

type ModelLister interface {
	List(ctx context.Context) ([]string, error)
}

type ModelSource struct {
	Provider  string `yaml:"provider"`
	URL       string `yaml:"url"` // e.g. https://ai.acme.example/v1/models
	APIKeyEnv string `yaml:"api_key_env,omitempty"`
	// Match filters ids worth evaluating (RE2), e.g. ^claude-(opus|sonnet)-.
	Match string `yaml:"match,omitempty"`
	// Known ids are never candidates (already evaluated or deliberately skipped).
	Known []string `yaml:"known,omitempty"`
	// Alias is the gateway model alias whose route the candidate pin edits
	// (models.<alias>.model in the Gateway document), e.g. sonnet-next.
	Alias string `yaml:"alias"`
}

type NPM struct {
	URL  string // default https://registry.npmjs.org
	HTTP *http.Client
}

type Registry interface {
	Latest(ctx context.Context, pkg string) (string, error)
}

type State struct {
	Handled map[string]string `json:"handled"` // candidate key -> verdict / PR url
}

type Verifier interface {
	Verify(ctx context.Context, harness, version string) (int, error)
}

type Watcher struct {
	PolicyDir string
	Config    *Config
	Registry  Registry
	Models    map[string]ModelLister // by provider; nil = HTTPModels from Config
	Verifier  Verifier
	Eval      EvalFunc         // required unless DryRun
	PR        promote.PROpener // required unless DryRun
	DryRun    bool
	// Warn receives non-fatal notices (e.g. a skipped malformed model id); nil = discard.
	Warn func(string)
}