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 (DESIGN §3.3) 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 (decision D-D): 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 (decision D-B): 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 v1 cannot
	// sequence (DESIGN D10), 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 ledger a caller both writes and edge-triggers
	// against (decision D-C).
	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 (DESIGN D9).
	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
}