deps

type BumpOptions struct {
	Options
	// Ecosystem selects which fleet graph and adapter the wave engine uses.
	// The zero value defaults to EcosystemGo for backward compatibility with
	// every caller that predates npm support.
	Ecosystem    Ecosystem
	MaxWaves     int
	PollInterval time.Duration
	RefreshAfter time.Duration
	Previous     *BumpReport
	Persist      func(BumpReport) error
	// NoRegistry forbids every registry lookup while retaining the shared
	// fleet-graph and wave-planning algorithm. Composite publication plans use
	// it before a provider workflow has published the proposed version.
	NoRegistry bool
	// FetchCache (the opt-in --fetch-cache flag) shares one process-local
	// orchestrate.FetchMemo across every graph-discovery and wave lifecycle of
	// this invocation. Only read-only DISCOVERY passes consume it: a
	// repository fetched during one wave's discovery is not re-fetched by
	// later waves' discovery while the memoized fetch is younger than
	// orchestrate.FetchMemoMaxAge, UNLESS this run has ever pushed to, opened
	// a PR for, or merged into it — such a repository is permanently
	// un-memoizable for the rest of the run, because WB merges server-side
	// and the resulting default-branch commits are invisible to any
	// local-push accounting. The wave engine's own pre-mutation fetch is
	// never skipped, so branch bases are always freshly fetched. Nothing is
	// persisted: a fresh invocation (including --resume) always starts with
	// an empty memo.
	FetchCache bool

	// Now is injectable for deterministic event-refresh tests.
	Now func() time.Time
	// LatestGoVersion is injectable for deterministic wave tests.
	LatestGoVersion func(context.Context, string) (string, error)
	// LatestGoRelease is injectable for graph traversal through modules that
	// were updated and published before this campaign started.
	LatestGoRelease func(context.Context, string) (PublishedGoRelease, error)
	// LatestNpmVersion is the npm-ecosystem analogue of LatestGoVersion.
	LatestNpmVersion func(context.Context, string) (string, error)
	// LatestNpmRelease is the npm-ecosystem analogue of LatestGoRelease. It
	// reuses PublishedGoRelease's shape (version, requirements, source) since
	// nothing about that shape is actually Go-specific.
	LatestNpmRelease func(context.Context, string) (PublishedGoRelease, error)

	// Scopes and ScopeResolutions carry a --latest run's derivation evidence
	// into the persisted report. They are set by the caller that ran
	// DeriveLatestReleaseEvents, because derivation happens before the wave
	// engine so that the derived events can be refused, printed, or reused
	// exactly like the hand-typed ones.
	Scopes           []string
	ScopeResolutions []LatestScopeResolution
}

type BumpPhase string

type BumpProgress struct {
	Wave                  int    `yaml:"wave,omitempty"`
	RepositoriesTotal     int    `yaml:"repositories_total,omitempty"`
	RepositoriesCompleted int    `yaml:"repositories_completed,omitempty"`
	LastRepository        string `yaml:"last_repository,omitempty"`
}

type BumpReport struct {
	SchemaVersion  int             `yaml:"schema_version"`
	Operation      string          `yaml:"operation"`
	Status         string          `yaml:"status"`
	Phase          BumpPhase       `yaml:"phase"`
	Progress       BumpProgress    `yaml:"progress"`
	Ecosystem      Ecosystem       `yaml:"ecosystem"`
	SeedEvents     []ReleaseEvent  `yaml:"seed_events"`
	GitHubDir      string          `yaml:"github_dir"`
	BaseRef        string          `yaml:"base_ref"`
	ValidationMode ValidationMode  `yaml:"validation_mode,omitempty"`
	Verification   []quality.Check `yaml:"verification,omitempty"`
	Parallel       int             `yaml:"parallel"`
	// ParallelExplicit records whether the operator set --parallel themselves
	// when this campaign ran. A resume without its own explicit --parallel
	// restores it, so "an explicit --parallel bounds every pool in both
	// directions" — including the read-only worker floor staying off for an
	// explicit --parallel 1 — survives interruption and resume.
	ParallelExplicit bool `yaml:"parallel_explicit,omitempty"`
	// RegistryLookupsSkipped records that this plan intentionally omitted
	// registry-derived carrier and stale-event evidence.
	RegistryLookupsSkipped bool `yaml:"registry_lookups_skipped,omitempty"`
	// FetchCacheEnabled records whether THIS invocation ran with the opt-in
	// --fetch-cache discovery memo, so a post-mortem (duplicate PR, stale
	// base, spun waves) can attribute or rule out memoized discovery reads.
	// It always reflects the live invocation, never a resumed report's past.
	FetchCacheEnabled bool `yaml:"fetch_cache_enabled,omitempty"`
	// ExcludedRepositories lists repositories --exclude removed before any
	// discovery ran, so a reader can tell "needed nothing" from "never looked
	// at".
	ExcludedRepositories []string `yaml:"excluded_repositories,omitempty"`
	// HeldRepositories lists every repository whose passing pull request this
	// campaign deliberately left open for its owner to merge, across all
	// waves.
	HeldRepositories []HeldRepository `yaml:"held_repositories,omitempty"`
	// Scopes records the --scope globs a --latest run derived its seed events
	// from, and ScopeResolutions every module those globs matched — including
	// the ones with no readable published version, which produced no event.
	// Without both, a report cannot distinguish "this scope publishes four
	// modules" from "four of this scope's modules could be read".
	Scopes                 []string                      `yaml:"scopes,omitempty"`
	ScopeResolutions       []LatestScopeResolution       `yaml:"scope_resolutions,omitempty"`
	DiscoverySkips         []GraphDiscoverySkip          `yaml:"discovery_skips,omitempty"`
	DefaultBranchFallbacks []GraphDefaultBranchFallback  `yaml:"default_branch_fallbacks,omitempty"`
	ManifestWarnings       []GraphManifestWarning        `yaml:"manifest_warnings,omitempty"`
	AmbiguousModules       []GraphAmbiguousModuleWarning `yaml:"ambiguous_modules,omitempty"`
	Waves                  []BumpWaveReport              `yaml:"waves"`
}

type BumpWaveReport struct {
	Index                int                   `yaml:"index"`
	Status               string                `yaml:"status"`
	ValidationMode       ValidationMode        `yaml:"validation_mode,omitempty"`
	Events               []ReleaseEvent        `yaml:"events"`
	Refreshes            []ReleaseEventRefresh `yaml:"refreshes,omitempty"`
	DeferredRepositories []string              `yaml:"deferred_repositories,omitempty"`
	Repositories         []RepositoryReport    `yaml:"repositories"`
	Releases             []ReleaseObservation  `yaml:"releases,omitempty"`
	// HeldRepositories are this wave's pull requests left open for a human.
	// A wave with any of them stops the campaign: a release that needs a
	// human merge cannot be waited for.
	HeldRepositories []HeldRepository `yaml:"held_repositories,omitempty"`
	// DiscoveryFetchesSkipped counts the origin fetches this wave's graph
	// discovery reused from the run's fetch memo (always zero without
	// --fetch-cache), attributing exactly how much the cache saved per wave.
	DiscoveryFetchesSkipped int `yaml:"discovery_fetches_skipped,omitempty"`
}

type Decision struct {
	Dependency    string    `yaml:"dependency,omitempty"`
	Ecosystem     Ecosystem `yaml:"ecosystem,omitempty"`
	File          string    `yaml:"file"`
	Selector      string    `yaml:"selector,omitempty"`
	BeforeRef     string    `yaml:"before_ref,omitempty"`
	BeforeVersion string    `yaml:"before_version,omitempty"`
	TargetVersion string    `yaml:"target_version"`
	ResolvedRef   string    `yaml:"resolved_ref,omitempty"`
	AfterRef      string    `yaml:"after_ref,omitempty"`
	AfterVersion  string    `yaml:"after_version,omitempty"`
	Action        string    `yaml:"action"`
	Reason        string    `yaml:"reason"`
}

type DependencyDelta struct {
	SourcePR         string    `yaml:"source_pr,omitempty"`
	SourceHead       string    `yaml:"source_head,omitempty"`
	Consumer         string    `yaml:"consumer"`
	Ecosystem        Ecosystem `yaml:"ecosystem"`
	Package          string    `yaml:"package"`
	Manifest         string    `yaml:"manifest"`
	Selector         string    `yaml:"selector"`
	Before           string    `yaml:"before"`
	RequestedAfter   string    `yaml:"requested_after"`
	CandidateAfter   string    `yaml:"candidate_after"`
	Lockfile         string    `yaml:"lockfile,omitempty"`
	LockfileSelector string    `yaml:"lockfile_selector,omitempty"`
	LockfileVersion  string    `yaml:"lockfile_version,omitempty"`
	Reviewed         bool      `yaml:"reviewed"`
}

type DirectiveAssessment struct {
	ModuleDir        string
	ModulePath       string
	CurrentGoVersion string
	CurrentToolchain string
	// TargetGoVersion is the exact `go` directive value the command would
	// write for a would-change or (after apply) compliant module. It may be
	// higher than the policy's baseline GoVersion when a dependency's ceiling
	// still falls within the same language version (e.g. policy 1.26.0 but a
	// dependency requires 1.26.4 exactly).
	TargetGoVersion string
	// Ceiling is the highest `go` directive found among this module's
	// dependencies in its resolved build list, independent of policy — empty
	// when the graph was not resolved (below-floor, error) or no dependency
	// declares one. It is the value Go's own MVS would require regardless of
	// what this module's own `go` line says.
	Ceiling string
	Verdict DirectiveVerdict
	Forcing []ForcingDependency
	Detail  string
}

type DirectivePolicy struct {
	GoVersion string
	Toolchain string
}

type DirectiveVerdict string

type DriftClassification string

type DriftDependency struct {
	Dependency string `json:"dependency" yaml:"dependency"`
	Manifest   string `json:"manifest" yaml:"manifest"`
	// Field names the manifest section the reference lives in. It is empty
	// for Go modules, whose go.mod require block has no sections, and set for
	// npm ("dependencies", "peerDependencies", "pnpm-override", …) where the
	// section changes what the reference means.
	Field       string           `json:"field,omitempty" yaml:"field,omitempty"`
	Declared    VersionEvidence  `json:"declared" yaml:"declared"`
	Selected    VersionEvidence  `json:"selected" yaml:"selected"`
	Replacement *ReplaceEvidence `json:"replacement,omitempty" yaml:"replacement,omitempty"`
	Latest      *VersionEvidence `json:"latest,omitempty" yaml:"latest,omitempty"`
	Edges       []DriftEdge      `json:"edges,omitempty" yaml:"edges,omitempty"`
}

type DriftEdge struct {
	ConsumerModule string `json:"consumer_module" yaml:"consumer_module"`
	Dependency     string `json:"dependency" yaml:"dependency"`
	Version        string `json:"version" yaml:"version"`
	Manifest       string `json:"manifest" yaml:"manifest"`
	Indirect       bool   `json:"indirect,omitempty" yaml:"indirect,omitempty"`
}

type DriftOptions struct {
	// Ecosystem selects which manifests are inspected: go.mod files, or
	// package.json/pnpm-workspace.yaml plus their governing lockfiles.
	Ecosystem    Ecosystem
	GitHubDir    string
	Ref          string
	Parallel     int
	Timeout      time.Duration
	Retry        int
	GoPrivate    []string
	Dependencies []string
	// Scopes are glob patterns matched against a dependency's module path or
	// package name, using path.Match semantics ("*" never crosses "/").
	// "@sneat/*" and "github.com/sneat-co/*" are the fleet's own-library
	// scopes; retaining only those is what keeps an --online run's registry
	// traffic proportional to the question being asked.
	Scopes []string
	// ExcludeRepositories are glob patterns matched against "owner/name".
	// A matching repository is never inspected and is reported as excluded.
	ExcludeRepositories []string
	Online              bool
	FailOnDrift         bool
	FailOnBehind        bool
	Now                 func() time.Time
	Progress            progress.Reporter
	// LatestNpmVersion overrides the registry lookup in tests. Production
	// runs leave it nil and consult the registry through pnpm.
	LatestNpmVersion func(ctx context.Context, module string) (string, error)
}

type DriftReport struct {
	SchemaVersion  int                  `json:"schema_version" yaml:"schema_version"`
	Ecosystem      Ecosystem            `json:"ecosystem" yaml:"ecosystem"`
	Mode           string               `json:"mode" yaml:"mode"`
	BaseRef        string               `json:"base_ref" yaml:"base_ref"`
	ObservedAt     time.Time            `json:"observed_at" yaml:"observed_at"`
	Summary        DriftSummary         `json:"summary" yaml:"summary"`
	Groups         []DriftVersionGroup  `json:"groups" yaml:"groups"`
	Repositories   []DriftRepository    `json:"repositories" yaml:"repositories"`
	DiscoverySkips []GraphDiscoverySkip `json:"discovery_skips,omitempty" yaml:"discovery_skips,omitempty"`
	// Excluded lists the repositories --exclude removed from the run, so an
	// operator can always tell "nothing to report" from "never inspected".
	Excluded []string `json:"excluded,omitempty" yaml:"excluded,omitempty"`
}

type DriftRepository struct {
	Repository   string            `json:"repository" yaml:"repository"`
	Path         string            `json:"path" yaml:"path"`
	Status       string            `json:"status" yaml:"status"`
	Reason       string            `json:"reason,omitempty" yaml:"reason,omitempty"`
	Dependencies []DriftDependency `json:"dependencies,omitempty" yaml:"dependencies,omitempty"`
}

type DriftSummary struct {
	Repositories int `json:"repositories" yaml:"repositories"`
	Dependencies int `json:"dependencies" yaml:"dependencies"`
	Converged    int `json:"converged" yaml:"converged"`
	Divergent    int `json:"divergent" yaml:"divergent"`
	Replaced     int `json:"replaced" yaml:"replaced"`
	MajorSplit   int `json:"major_path_split" yaml:"major_path_split"`
	Unavailable  int `json:"unavailable" yaml:"unavailable"`
	Error        int `json:"error" yaml:"error"`
	// Behind counts groups where at least one repository provably installs
	// or admits something older than the registry's latest release. It is
	// orthogonal to the classification ladder: a group can be both divergent
	// and behind, and both facts matter.
	Behind int `json:"behind" yaml:"behind"`
}

type DriftVersionGroup struct {
	Dependency     string              `json:"dependency" yaml:"dependency"`
	Family         string              `json:"family,omitempty" yaml:"family,omitempty"`
	Classification DriftClassification `json:"classification" yaml:"classification"`
	Versions       []DriftVersionUse   `json:"versions" yaml:"versions"`
	MajorPaths     []string            `json:"major_paths,omitempty" yaml:"major_paths,omitempty"`
	Latest         *VersionEvidence    `json:"latest,omitempty" yaml:"latest,omitempty"`
	Reason         string              `json:"reason,omitempty" yaml:"reason,omitempty"`
	// Behind is true when at least one repository provably lags the observed
	// latest release. BehindRepositories names them, and BehindReason says
	// what the evidence was.
	Behind             bool     `json:"behind,omitempty" yaml:"behind,omitempty"`
	BehindRepositories []string `json:"behind_repositories,omitempty" yaml:"behind_repositories,omitempty"`
	BehindReason       string   `json:"behind_reason,omitempty" yaml:"behind_reason,omitempty"`
}

type DriftVersionUse struct {
	Version      string   `json:"version" yaml:"version"`
	Kind         string   `json:"kind" yaml:"kind"` // selected or declared
	Repositories []string `json:"repositories" yaml:"repositories"`
}

type Ecosystem string

type ForcingDependency struct {
	Path      string `json:"path"`
	Version   string `json:"version"`
	GoVersion string `json:"goVersion"`
}

type Graph struct {
	SchemaVersion int                `json:"schema_version" yaml:"schema_version"`
	Ecosystem     Ecosystem          `json:"ecosystem" yaml:"ecosystem"`
	BaseRef       string             `json:"base_ref" yaml:"base_ref"`
	Filters       GraphFilters       `json:"filters" yaml:"filters"`
	Summary       GraphSummary       `json:"summary" yaml:"summary"`
	Order         GraphOrder         `json:"order" yaml:"order"`
	Repositories  []GraphRepository  `json:"repositories" yaml:"repositories"`
	Modules       []GraphModule      `json:"modules" yaml:"modules"`
	Requirements  []GraphRequirement `json:"requirements" yaml:"requirements"`
	// DiscoverySkips lists repositories excluded from the walk rather than
	// inspected. It belongs to the graph rather than to a log line so that no
	// output format can present a partial fleet as a complete one.
	DiscoverySkips []GraphDiscoverySkip `json:"discovery_skips,omitempty" yaml:"discovery_skips,omitempty"`
	// DefaultBranchFallbacks lists repositories fully discovered using their
	// actual default branch because the configured base ref did not exist.
	DefaultBranchFallbacks []GraphDefaultBranchFallback `json:"default_branch_fallbacks,omitempty" yaml:"default_branch_fallbacks,omitempty"`
	// ManifestWarnings lists non-root manifest files skipped for failing to
	// parse instead of aborting discovery.
	ManifestWarnings []GraphManifestWarning `json:"manifest_warnings,omitempty" yaml:"manifest_warnings,omitempty"`
	// AmbiguousModules lists modules declared by more than one repository
	// whose conflict was deterministically resolved instead of aborting the
	// fleet (Go only; see GraphAmbiguousModuleWarning).
	AmbiguousModules []GraphAmbiguousModuleWarning `json:"ambiguous_modules,omitempty" yaml:"ambiguous_modules,omitempty"`
}

type GraphAmbiguousModuleWarning struct {
	Module     string   `json:"module" yaml:"module"`
	Repository string   `json:"repository" yaml:"repository"`
	Manifest   string   `json:"manifest" yaml:"manifest"`
	Duplicates []string `json:"duplicates" yaml:"duplicates"`
	Reason     string   `json:"reason" yaml:"reason"`
}

type GraphDefaultBranchFallback struct {
	Repository string `json:"repository" yaml:"repository"`
	Ref        string `json:"ref" yaml:"ref"`
}

type GraphDiscoverySkip struct {
	Repository string `json:"repository" yaml:"repository"`
	Reason     string `json:"reason" yaml:"reason"`
}

type GraphFilters struct {
	Dependencies []string `json:"dependencies,omitempty" yaml:"dependencies,omitempty"`
}

type GraphManifestWarning struct {
	Repository string `json:"repository" yaml:"repository"`
	Manifest   string `json:"manifest" yaml:"manifest"`
	Reason     string `json:"reason" yaml:"reason"`
}

type GraphModule struct {
	Path       string `json:"path" yaml:"path"`
	Repository string `json:"repository" yaml:"repository"`
	Manifest   string `json:"manifest" yaml:"manifest"`
}

type GraphOptions struct {
	Ecosystem    Ecosystem
	GitHubDir    string
	Ref          string
	Parallel     int
	Timeout      time.Duration
	Retry        int
	Dependencies []string
	Progress     progress.Reporter
}

type GraphOrder struct {
	Layers []GraphOrderLayer `json:"layers,omitempty" yaml:"layers,omitempty"`
	Cycles []GraphOrderCycle `json:"cycles,omitempty" yaml:"cycles,omitempty"`
}

type GraphOrderCycle struct {
	Layer        int      `json:"layer" yaml:"layer"`
	Repositories []string `json:"repositories" yaml:"repositories"`
	Path         string   `json:"path" yaml:"path"`
}

type GraphOrderLayer struct {
	Index        int      `json:"index" yaml:"index"`
	Repositories []string `json:"repositories" yaml:"repositories"`
}

type GraphProjection struct {
	View  GraphView
	Nodes []GraphProjectionNode
	Edges []GraphProjectionEdge
}

type GraphProjectionEdge struct {
	ID            string
	From          string
	To            string
	DirectCount   int
	IndirectCount int
	Status        string
	Evidence      []string
}

type GraphProjectionNode struct {
	ID             string
	Kind           string
	Label          string
	Subtitle       string
	Status         string
	Repository     string
	Dependency     string
	Version        string
	GitHubURL      string
	CodeGrapherURL string
	Organization   string
}

type GraphReportPaths struct {
	Markdown string
	YAML     string
	JSON     string
	SVG      string
	HTML     string
}

type GraphRepository struct {
	Slug         string   `json:"slug" yaml:"slug"`
	Organization string   `json:"organization" yaml:"organization"`
	Modules      []string `json:"modules,omitempty" yaml:"modules,omitempty"`
}

type GraphRequirement struct {
	Dependency         string   `json:"dependency" yaml:"dependency"`
	Version            string   `json:"version" yaml:"version"`
	ConsumerModule     string   `json:"consumer_module" yaml:"consumer_module"`
	ConsumerRepository string   `json:"consumer_repository" yaml:"consumer_repository"`
	Manifest           string   `json:"manifest" yaml:"manifest"`
	Indirect           bool     `json:"indirect,omitempty" yaml:"indirect,omitempty"`
	ProviderModule     string   `json:"provider_module,omitempty" yaml:"provider_module,omitempty"`
	ProviderRepository string   `json:"provider_repository,omitempty" yaml:"provider_repository,omitempty"`
	ProviderCandidates []string `json:"provider_candidates,omitempty" yaml:"provider_candidates,omitempty"`
}

type GraphSummary struct {
	Repositories         int `json:"repositories" yaml:"repositories"`
	Modules              int `json:"modules" yaml:"modules"`
	Requirements         int `json:"requirements" yaml:"requirements"`
	InternalRequirements int `json:"internal_requirements" yaml:"internal_requirements"`
	ExternalDependencies int `json:"external_dependencies" yaml:"external_dependencies"`
	Selections           int `json:"selections" yaml:"selections"`
	AmbiguousProviders   int `json:"ambiguous_providers" yaml:"ambiguous_providers"`
}

type GraphView string

type HeldRepository struct {
	Repository string `yaml:"repository"`
	PR         string `yaml:"pr,omitempty"`
	Reason     string `yaml:"reason,omitempty"`
}

type LatestScopeResolution struct {
	Dependency string `yaml:"dependency"`
	Repository string `yaml:"repository,omitempty"`
	Version    string `yaml:"version,omitempty"`
	Reason     string `yaml:"reason,omitempty"`
}

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

type Options struct {
	GitHubDir string
	Ref       string
	Parallel  int
	// ParallelExplicit records that the operator set --parallel themselves.
	// An explicit value bounds every pool, including the read-only graph
	// discovery and release-observation pools; when it is left at its default
	// those read-only pools get the wider readOnlyWorkerCount floor instead
	// (mutating lifecycle stages always keep the Parallel bound).
	ParallelExplicit bool
	DryRun           bool
	Resume           bool
	AllowDowngrade   bool
	ValidationMode   ValidationMode
	Verify           bool
	Checks           []quality.Check
	Timeout          time.Duration
	Retry            int
	// CheckPollInterval overrides the GitHub-check polling delay of orchestrated
	// CI waits. A zero value uses the production default. It is primarily
	// useful for deterministic lifecycle tests (see
	// orchestrate.Options.CheckPollInterval).
	CheckPollInterval time.Duration
	// GoPrivate supplies comma-separated Go module path patterns that must not
	// be looked up through a public module proxy or checksum database. The
	// patterns are merged with the caller's GOPRIVATE/GONOPROXY/GONOSUMDB only
	// for Go subprocesses; WB never writes Go's global environment.
	GoPrivate []string
	Commit    bool
	Push      bool
	PR        bool
	Merge     bool
	ReportDir string
	// Order sequences repositories in provider-first dependency layers derived
	// from the selected repositories' own module declarations and requirements,
	// instead of processing the whole selection as one batch.
	Order bool
	// Layers restricts an ordered run to one layer or a contiguous range so an
	// operator can land one layer before starting the next.
	Layers LayerSelection
	// ExcludeRepositories are "owner/name" globs removed from the run before
	// anything is discovered: no graph entry, no wave membership, no
	// worktree, no pull request. Use it for a repository the campaign has no
	// business touching at all.
	ExcludeRepositories []string
	// Hold are "owner/name" globs whose merge is a human decision. A held
	// repository is bumped, verified, pushed, has its pull request opened and
	// its exact PR-head checks waited on — and is then left OPEN even under
	// --merge. It is the opposite of exclusion: the mechanical work is done,
	// only the irreversible step waits for its owner.
	Hold     []string
	Progress progress.Reporter

	// ResolveGitHubRef is injectable for hermetic adapter tests.
	ResolveGitHubRef func(context.Context, string, string) (string, error)
}

type OrderLayerReport struct {
	Index        int      `yaml:"index"`
	Repositories []string `yaml:"repositories"`
	Status       string   `yaml:"status"`
}

type OrderReport struct {
	Selection string             `yaml:"selection"`
	Layers    []OrderLayerReport `yaml:"layers"`
	Cycles    []GraphOrderCycle  `yaml:"cycles,omitempty"`
}

type PeerOptions struct {
	// Package is the published package, optionally pinned: "@sneat/core" or
	// "@sneat/core@0.31.0". Unpinned means the registry's "latest".
	Package string
	// Against is the path of the checkout whose installed versions the peers
	// are judged against.
	Against string
	Timeout time.Duration
	Retry   int
	// PublishedPeers is injectable so the whole verdict table can be tested
	// without a network round trip.
	PublishedPeers func(ctx context.Context, pkg string) (PublishedPeerSet, error)
	// Now is injectable for deterministic timestamps.
	Now func() time.Time
}

type PeerReport struct {
	SchemaVersion int         `json:"schema_version" yaml:"schema_version"`
	Package       string      `json:"package" yaml:"package"`
	Version       string      `json:"version,omitempty" yaml:"version,omitempty"`
	Source        string      `json:"source,omitempty" yaml:"source,omitempty"`
	Against       string      `json:"against" yaml:"against"`
	AgainstName   string      `json:"against_name,omitempty" yaml:"against_name,omitempty"`
	ObservedAt    time.Time   `json:"observed_at" yaml:"observed_at"`
	Peers         []PeerRow   `json:"peers" yaml:"peers"`
	Summary       PeerSummary `json:"summary" yaml:"summary"`
}

type PeerRow struct {
	Peer     string `json:"peer" yaml:"peer"`
	Required string `json:"required" yaml:"required"`
	Optional bool   `json:"optional,omitempty" yaml:"optional,omitempty"`
	// Installed is what the target actually resolves, and InstalledSource is
	// the lockfile or manifest field that says so. An answer with no evidence
	// trail is not an answer.
	Installed       string `json:"installed,omitempty" yaml:"installed,omitempty"`
	InstalledSource string `json:"installed_source,omitempty" yaml:"installed_source,omitempty"`
	Verdict         string `json:"verdict" yaml:"verdict"`
	Reason          string `json:"reason,omitempty" yaml:"reason,omitempty"`
}

type PeerSummary struct {
	Total           int `json:"total" yaml:"total"`
	Satisfied       int `json:"satisfied" yaml:"satisfied"`
	Unsatisfied     int `json:"unsatisfied" yaml:"unsatisfied"`
	Missing         int `json:"missing" yaml:"missing"`
	OptionalMissing int `json:"optional_missing" yaml:"optional_missing"`
	Unevaluated     int `json:"unevaluated" yaml:"unevaluated"`
}

type PublishedGoRelease struct {
	Version      string
	Requirements map[string]string
	Source       string
}

type PublishedPeerSet struct {
	Version  string
	Peers    map[string]string
	Optional map[string]bool
	Source   string
}

type ReleaseEvent struct {
	Dependency string `yaml:"dependency"`
	Version    string `yaml:"version"`
	Source     string `yaml:"source"`
	// CheckedAt is when WB accepted this version from the operator or last
	// confirmed it against the registry. Persisting it lets a resumed or
	// long-running campaign refresh stale events before spending another CI
	// build on a downstream PR.
	CheckedAt time.Time `yaml:"checked_at,omitempty"`
}

type ReleaseEventRefresh struct {
	Dependency string    `yaml:"dependency"`
	Before     string    `yaml:"before"`
	After      string    `yaml:"after"`
	CheckedAt  time.Time `yaml:"checked_at"`
	Reason     string    `yaml:"reason"`
}

type ReleaseObservation struct {
	Module               string            `yaml:"module"`
	Repository           string            `yaml:"repository"`
	Before               string            `yaml:"before,omitempty"`
	After                string            `yaml:"after,omitempty"`
	Source               string            `yaml:"source"`
	Status               string            `yaml:"status"`
	Reason               string            `yaml:"reason"`
	ExpectedRequirements map[string]string `yaml:"expected_requirements,omitempty"`
	RequireNewer         bool              `yaml:"require_newer,omitempty"`
	CheckedAt            time.Time         `yaml:"checked_at,omitempty"`
}

type RemoteCheck = orchestrate.RemoteCheck

type ReplaceEvidence struct {
	OldPath    string    `json:"old_path" yaml:"old_path"`
	OldVersion string    `json:"old_version,omitempty" yaml:"old_version,omitempty"`
	NewPath    string    `json:"new_path" yaml:"new_path"`
	NewVersion string    `json:"new_version,omitempty" yaml:"new_version,omitempty"`
	Local      bool      `json:"local" yaml:"local"`
	ObservedAt time.Time `json:"observed_at" yaml:"observed_at"`
	Source     string    `json:"source" yaml:"source"`
}

type Report struct {
	SchemaVersion  int                `yaml:"schema_version"`
	Operation      string             `yaml:"operation"`
	Status         string             `yaml:"status"`
	Target         Target             `yaml:"target"`
	GitHubDir      string             `yaml:"github_dir"`
	BaseRef        string             `yaml:"base_ref"`
	ValidationMode ValidationMode     `yaml:"validation_mode,omitempty"`
	Verification   []quality.Check    `yaml:"verification,omitempty"`
	Parallel       int                `yaml:"parallel"`
	Order          *OrderReport       `yaml:"order,omitempty"`
	Repositories   []RepositoryReport `yaml:"repositories"`
}

type Repository = orchestrate.Repository

type RepositoryReport struct {
	Repository   string     `yaml:"repository"`
	CanonicalDir string     `yaml:"canonical_dir,omitempty"`
	WorktreeDir  string     `yaml:"worktree_dir,omitempty"`
	Branch       string     `yaml:"branch,omitempty"`
	Ref          string     `yaml:"ref"`
	Status       string     `yaml:"status"`
	Reason       string     `yaml:"reason"`
	Decisions    []Decision `yaml:"decisions,omitempty"`
	// DependencyDeltas is the exact per-reference evidence emitted for each
	// generated pull request. It is the campaign-side source for a later
	// supersession receipt, not a family-level inference.
	DependencyDeltas []DependencyDelta           `yaml:"dependency_deltas,omitempty"`
	ChangedFiles     []string                    `yaml:"changed_files,omitempty"`
	Verifications    []quality.VerificationEntry `yaml:"verifications,omitempty"`
	Commit           string                      `yaml:"commit,omitempty"`
	Pushed           bool                        `yaml:"pushed,omitempty"`
	PR               string                      `yaml:"pr,omitempty"`
	Checks           []RemoteCheck               `yaml:"checks,omitempty"`
	Merged           bool                        `yaml:"merged,omitempty"`
	// Held records that --hold matched this repository, so its passing pull
	// request was deliberately left open for its owner to merge.
	Held bool `yaml:"held,omitempty"`
}

type Target struct {
	Ecosystem  Ecosystem `yaml:"ecosystem"`
	Dependency string    `yaml:"dependency"`
	Version    string    `yaml:"version"`
	Resolved   string    `yaml:"resolved,omitempty"`
}

type ValidationMode string

type VersionEvidence struct {
	Value      string    `json:"value,omitempty" yaml:"value,omitempty"`
	ObservedAt time.Time `json:"observed_at" yaml:"observed_at"`
	Source     string    `json:"source" yaml:"source"`
	Reason     string    `json:"reason,omitempty" yaml:"reason,omitempty"`
}