inputs

type GraphVerdict struct {
	Valid   bool
	Reason  string
	Message string
}

type Hold struct {
	Manager string
	Kind    HoldKind
}

type HoldKind string

type Params struct {
	Wavefront *wavefrontv1alpha1.Wavefront
	Adapter   adapter.Adapter
	Strategy  selection.Strategy
	// Observations is the caller's own coherent snapshot of the poller; nil
	// (or a missing entry) means unobserved. Strict ordering for co-arriving
	// changes is only structural if every node is evaluated against the same
	// sweep, so the snapshot is taken by the caller — once, before anything
	// reconfigures the poller — never re-read per source here.
	Observations map[types.NamespacedName]gitpoll.Observation
}

type Result struct {
	// discovery
	Nodes    map[adapter.NodeRef]adapter.Node // selected set plus dependsOn closure
	Selected map[adapter.NodeRef]bool
	Missing  map[adapter.NodeRef]bool // dependsOn targets that do not exist

	// source resolution
	Inputs map[adapter.NodeRef]engine.NodeInput
	Repos  map[types.NamespacedName]*sourcev1.GitRepository
	// NodeBySource lists every selected, pinned node referencing a source,
	// each slice in compareRefs order: a shared source's events and status
	// attribution need every referencing node, not just whichever last
	// overwrote a single value.
	NodeBySource map[types.NamespacedName][]adapter.NodeRef
	// Holds is the unified hold ledger: every source the engine reports Held
	// for, whether a hand-pin (a foreign field manager owns spec.ref.commit)
	// or a suspend (spec.suspend). It feeds counts.Held, status.held[], the
	// HoldDetected/HoldReleased edge-trigger and the admission gate alike. A
	// caller that discovers a further hold while executing (an SSA conflict,
	// pin.ErrHeld) may add to it after Build returns.
	Holds   map[types.NamespacedName]Hold
	Targets []gitpoll.Target
	// UnsupportedSources lists managed sources whose ref style (currently:
	// semver tracking, which only a future SemverWindow strategy could
	// sequence) selection.TrackRef cannot resolve, demoted to gates.
	// Recorded once per source and sorted, so a caller can announce each
	// exactly once.
	UnsupportedSources []types.NamespacedName

	// fleet
	Wavefronts *wavefrontv1alpha1.WavefrontList
	Overlap    string // name of the Wavefront whose selector overlaps this one

	// graph and evaluation
	Graph  *graph.Graph
	Cycles [][]adapter.NodeRef
	Eval   engine.Evaluation

	// Resolved and GraphChecked record how far the pass got: an aborted pass
	// has proven nothing about the fleet (Resolved false) and, before
	// derivation, nothing about the graph either (GraphChecked false).
	Resolved     bool
	GraphChecked bool
}

type Summary struct {
	Counts wavefrontv1alpha1.NodeCounts
	Phase  wavefrontv1alpha1.Phase
	// Blocked and Held are the capped status lists; Held is exactly
	// HeldSources(res): the same capped, source-sorted list that both becomes
	// status.held and is diffed pass-to-pass to edge-trigger the
	// HoldDetected/HoldReleased events, rather than an unbounded internal
	// ledger.
	Blocked []wavefrontv1alpha1.BlockedNode
	Held    []wavefrontv1alpha1.HeldNode
	// Members is every evaluated node's derived state, sorted by
	// kind/namespace/name and capped at MembersCap; MembersOmitted counts the
	// remainder. Write-only output: nothing here or in the reconciler ever
	// reads it back — admissibility is re-derived from live cluster state on
	// every pass, never from a previous status write.
	Members        []wavefrontv1alpha1.Member
	MembersOmitted int
	// BlockedByReason is uncapped, unlike Blocked: a gauge must count every
	// blocked node, not just the ones that fit the status list.
	BlockedByReason map[engine.BlockedReason]int
	FetchFailures   int
}